window_helper.h

Go to the documentation of this file.

//            _             _                     _            _                     _      //
// __      __(_) _ __    __| |  ___ __      __   | |__    ___ | | _ __    ___  _ __ | |__   //
// \ \ /\ / /| || '_ \  / _` | / _ \\ \ /\ / /   | '_ \  / _ \| || '_ \  / _ \| '__|| '_ \  //
//  \ V  V / | || | | || (_| || (_) |\ V  V /    | | | ||  __/| || |_) ||  __/| | _ | | | | //
//   \_/\_/  |_||_| |_| \__,_| \___/  \_/\_/_____|_| |_| \___||_|| .__/  \___||_|(_)|_| |_| //
//                                         |_____|               |_|                        //
//                                                                                          //
//                       basic window creation and message handling                         //
//                                                                                          //
//              NOTE:  'WB' is for 'Work Bench', aka 'X11workbench Toolkit'                 //
//                                                                                          //

/*****************************************************************************

    X11workbench - X11 programmer's 'work bench' application and toolkit
    Copyright (c) 2010-2019 by Bob Frazier (aka 'Big Bad Bombastic Bob')

  DISCLAIMER:  The X11workbench application and toolkit software are supplied
               'as-is', with no warranties, either implied or explicit.
               Any claims to alleged functionality or features should be
               considered 'preliminary', and might not function as advertised.

  MIT-like license:

  There is no restriction as to what you can do with this software, so long
  as you include the above copyright notice and DISCLAIMER for any distributed
  work that is equal to or derived from this one, along with this paragraph
  that explains the terms of the license if the source is also being made
  available.  A "derived work" describes a work that uses a significant portion
  of the source files or algorithms that are included with this one.
  Specifically excluded from this are files that were generated by the software,
  or anything that is included with the software that is part of another package
  (such as files that were created or added during the 'configure' process).
  Specifically included is the use of part or all of any of the X11 workbench
  toolkit source or header files in your distributed application.  If you do not
  ship the source, the above copyright statement is still required to be placed
  in a reasonably prominent place, such as documentation, splash screens, and/or
  'about the application' dialog boxes.

  Use and distribution are in accordance with GPL, LGPL, and/or the above
  MIT-like license.  See COPYING and README files for more information.


  Additional information at http://sourceforge.net/projects/X11workbench

******************************************************************************/


//      - DOXYGEN RELATED STUFF -       //

// doxygen top-level stuff has been moved to doxy_comments.dox

//    - END DOXYGEN RELATED STUFF -     //


// window helpers - defines manager for callback procs, font, GC, and a generic event dispatcher

#ifndef WINDOW_HELPER_H_INCLUDED
#define WINDOW_HELPER_H_INCLUDED


#ifndef WIN32
#ifdef COMPILER_HAS_PRAGMA_FOR_INCOMPATIBLE_POINTER_TYPES
// the 'incompatible pointer types' is now an error (not all gcc supports this)
#pragma GCC diagnostic error "-Wincompatible-pointer-types"
#endif // COMPILER_HAS_PRAGMA_FOR_INCOMPATIBLE_POINTER_TYPES
#endif // !WIN32


// headers that must be included or I break

#include <string.h>   // for memset, mostly

#ifndef __DOXYGEN__ /* exclude these so I don't mess up the docs */
#include "platform_helper.h"
#include "debug_helper.h"
#include "font_helper.h"
#endif // __DOXYGEN__

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

#define WB_DEFAULT_CURSOR XC_left_ptr

#define WB_WAIT_CURSOR XC_watch /*XC_clock*/

#define WB_DEFAULT_FONT    "fixed"

#define WB_DEFAULT_FONT_SIZE 13 /* override via settings */

#define WINDOW_DATA_SIZE 4 /* size of a 'void *' array that stores per-window data */

#define EVENT_ALL_MASK 0x01ffffffL /* 2^24 | 2^23 ... 2^0 - see X.h */


#define GCAll (GCFunction | GCPlaneMask | GCForeground | GCBackground | GCLineWidth | \
               GCLineStyle | GCCapStyle | GCJoinStyle | GCFillStyle | GCFillRule | \
               GCTile | GCStipple | GCTileStipXOrigin | GCTileStipYOrigin | GCFont | \
               GCSubwindowMode | GCGraphicsExposures | GCClipXOrigin | GCClipYOrigin | \
               GCClipMask | GCDashOffset | GCDashList | GCArcMode)



// debug helpers (may be eliminated at some point)

extern const char *sz_xcall_func;
extern int i_xcall_line;
#define BEGIN_XCALL_DEBUG_WRAPPER { const char *__szOldXCallFunc__ = sz_xcall_func; int __iOldXCallLine__ = i_xcall_line; sz_xcall_func = __FUNCTION__;  i_xcall_line = __LINE__; {

#define END_XCALL_DEBUG_WRAPPER   } sz_xcall_func = __szOldXCallFunc__;  i_xcall_line = __iOldXCallLine__; }


typedef int (* WBWinEvent)(Window wID, XEvent *pEvent);
typedef int (* WBAppEvent)(XEvent *pEvent);


//                                                                                        //
//    ____                    ____   _                       _                            //
//   / ___| ___   _ __  ___  / ___| | |_  _ __  _   _   ___ | |_  _   _  _ __  ___  ___   //
//  | |    / _ \ | '__|/ _ \ \___ \ | __|| '__|| | | | / __|| __|| | | || '__|/ _ \/ __|  //
//  | |___| (_) || |  |  __/  ___) || |_ | |   | |_| || (__ | |_ | |_| || |  |  __/\__ \  //
//   \____|\___/ |_|   \___| |____/  \__||_|    \__,_| \___| \__| \__,_||_|   \___||___/  //
//                                                                                        //
//                                                                                        //


typedef struct s_WBGC
{
  Display *display;   
  Drawable dw;        
  GC gc;              
  XGCValues values;   
  WB_FONT pFont;      
  Region clip_rgn;    
  XImage *clip_image; 
  XImage *tile_image; 
  XImage *stip_image; 
} * WBGC;

typedef struct s_WB_POINT
{
  int x;   
  int y;   
} WB_POINT;

typedef struct s_WB_EXTENT
{
  unsigned int width;   
  unsigned int height;  
} WB_EXTENT;

typedef struct s_WB_RECT
{
  int left;   
  int top;    
  int right;  
  int bottom; 
} WB_RECT;

typedef struct s_WB_GEOM
{
  int x; 
  int y; 
  unsigned int width; 
  unsigned int height; 
  unsigned int border; 
} WB_GEOM;



//                                                                                                                               //
//   ____   _                _                      _                _   ____   _             _       _                          //
//  / ___| | |_  __ _  _ __ | |_  _   _  _ __      / \    _ __    __| | / ___| | |__   _   _ | |_  __| |  ___ __      __ _ __    //
//  \___ \ | __|/ _` || '__|| __|| | | || '_ \    / _ \  | '_ \  / _` | \___ \ | '_ \ | | | || __|/ _` | / _ \\ \ /\ / /| '_ \   //
//   ___) || |_| (_| || |   | |_ | |_| || |_) |  / ___ \ | | | || (_| |  ___) || | | || |_| || |_| (_| || (_) |\ V  V / | | | |  //
//  |____/  \__|\__,_||_|    \__| \__,_|| .__/  /_/   \_\|_| |_| \__,_| |____/ |_| |_| \__,_| \__|\__,_| \___/  \_/\_/  |_| |_|  //
//                                      |_|                                                                                      //
//                                                                                                                               //


// window-specific initialization

Display *WBInit(const char *szDisplayName);

int WBInitDisplay(Display *pDisplay);

int WBInitClipboardSystem(Display *pDisplay, const char *szDisplayName);

int __StartInitClipboardSystem(Display *pDisplay, const char *szDisplayName);

int __FinishInitClipboardSystem(Display *pDisplay, const char *szDisplayName);


void WBExit(void);

void WBExitClipboardSystem(Display *pDisplay);

Display *WBThreadInitDisplay(void);

void WBThreadFreeDisplay(Display *pThreadDisplay);


const char *GetStartupDisplayName(void);

void GetStartupGeometry(WB_GEOM *pGeom);
int GetStartupMinMax(void);

#if defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)
static __inline__ Colormap WBDefaultColormap(Display *pDisplay)
{
  return DefaultColormap(pDisplay, DefaultScreen(pDisplay));
}
#else // defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)
#define WBDefaultColormap(X) DefaultColormap(pDisplay, DefaultScreen(pDisplay))
#endif // defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)


void WBInitWindowAttributes(XSetWindowAttributes *pXSWA, unsigned long lBorderPixel,
                            unsigned long lBackgroundPixel, Colormap clrMap, int iBitGravity);

void WBInitSizeHints(XSizeHints *pSH, Display *pDisplay, int iMinHeight, int iMinWidth);



//   ____   _____  _____  _    _   _  _    _____  ____    //
//  |  _ \ | ____||  ___|/ \  | | | || |  |_   _|/ ___|   //
//  | | | ||  _|  | |_  / _ \ | | | || |    | |  \___ \   //
//  | |_| || |___ |  _|/ ___ \| |_| || |___ | |   ___) |  //
//  |____/ |_____||_| /_/   \_\\___/ |_____||_|  |____/   //
//                                                        //

#if defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)
static __inline__ Display * WBGetDefaultDisplay(void)
{
  extern Display *pDefaultDisplay;
  return pDefaultDisplay;
}
#else // defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)
Display *WBGetDefaultDisplay();
#endif // defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)

WB_FONTC WBGetDefaultFont(void);

Window WBGetHiddenHelperWindow(void);  // if you need "a window" for the default display, use this




//    ____  _      ___   ____     _     _           _   _____  ___   __  __  ____    //
//   / ___|| |    / _ \ | __ )   / \   | |         / \ |_   _|/ _ \ |  \/  |/ ___|   //
//  | |  _ | |   | | | ||  _ \  / _ \  | |        / _ \  | | | | | || |\/| |\___ \   //
//  | |_| || |___| |_| || |_) |/ ___ \ | |___    / ___ \ | | | |_| || |  | | ___) |  //
//   \____||_____|\___/ |____//_/   \_\|_____|  /_/   \_\|_|  \___/ |_|  |_||____/   //
//                                                                                   //

// global atoms (for convenience they are referenced directly via global variables)

#if !defined(_WINDOW_HELPER_C_) && !defined(_CLIPBOARD_HELPER_C) && !defined(__DOXYGEN__)
     /* this declares the atoms 'const' outside of window_helper.c, and does NOT declare them in clipboard_helper.c */
     /* These atoms are GLOBAL variables, assigned by the DEFAULT Display, and may not work for other threads.      */
extern const Atom aMENU_COMMAND;     // commands sent by menus via ClientMessage
extern const Atom aMENU_UI_COMMAND;  // UI notification sent by menus to owning frame windows via ClientMessage using WBWindowDispatch
extern const Atom aRESIZE_NOTIFY;    // notification of window re-size via ClientMessage
extern const Atom aDESTROY_NOTIFY;   // notify parent that child is being destroyed
extern const Atom aCONTROL_NOTIFY;   // dialog control and child window notification messages
                                     // l[0] contains control ID or -1, l[1] is notify code, l[2] is window ID
extern const Atom aSCROLL_NOTIFY;    // specific notification for scrollbars (see enumeration, below)
                                     // data.l[0] is scrollbar enum, data.l[1] is notification enum, data.l[2] is optional position modifier
extern const Atom aQUERY_CLOSE;      // command sent by Client Message - return 0 if ok to close, 1 if not ok to close, -1 on error
extern const Atom aRECALC_LAYOUT;    // notify window that it should re-calculate things like scrollbars and viewports

extern const Atom aDLG_FOCUS;        // dialog focus messages: l[0] is <,0,> for prev, 'set to', next.  For 'set to' l[1] is control ID
extern const Atom aSET_FOCUS;        // 'set focus' messages (send/post to application)
extern const Atom aWB_CHAR;          // character notifications (generated by API; avoids key up/down handling)
extern const Atom aWB_TIMER;         // timer notifications (generated by API)
extern const Atom aWB_POINTER;       // pointer notifications (generated by API)

// things used by window managers
extern const Atom aWM_PROTOCOLS;     // WM supported protocols (see 'freedesktop.org' WM docs)
extern const Atom aWM_DELETE_WINDOW; // WM command to delete a window (a click on the 'x')
extern const Atom aWM_TAKE_FOCUS;    // WM protocol (part of WM_PROTOCOLS spec, ICCCM, assoc with focus bit in WM_HINTS)

// things used by fonts
extern const Atom aAVERAGE_WIDTH;    // Average Character Width (font property)

// things used by the clipboard
extern const Atom aCLIPBOARD;        // Atom for 'CLIPBOARD'
extern const Atom aPRIMARY;          // Atom for 'PRIMARY'
extern const Atom aSECONDARY;        // Atom for 'SECONDARY'
extern const Atom aMANAGER;          // Atom for 'MANAGER'
extern const Atom aTARGET;           // Atom for 'TARGET'
extern const Atom aINCR;             // Atom for 'INCR' (incremental transfers)
extern const Atom aWINDOW;           // Atom for 'WINDOW'
extern const Atom aBITMAP;           // Atom for 'BITMAP'
extern const Atom aDRAWABLE;         // Atom for 'DRAWABLE'
extern const Atom aCOLORMAP;         // Atom for 'COLORMAP'
extern const Atom aPIXEL;            // Atom for 'PIXEL'
extern const Atom aPIXMAP;           // Atom for 'PIXMAP'
extern const Atom aTEXT;             // Atom for 'TEXT'
extern const Atom aSTRING;           // Atom for 'STRING'
extern const Atom aUTF8_STRING;      // Atom for 'UTF8_STRING'
extern const Atom aC_STRING;         // Atom for 'C_STRING'
extern const Atom aCOMPOUND_TEXT;    // Atom for 'COMPOUND_TEXT'
extern const Atom aTARGETS;          // Atom for 'TARGETS'
extern const Atom aMULTIPLE;         // Atom for 'MULTIPLE'
extern const Atom aTIMESTAMP;        // Atom for 'TIMESTAMP'
extern const Atom aNULL;             // Atom for 'NULL'
#endif // !_WINDOW_HELPER_C, !_CLIPBOARD_HELPER_C



// parameter enumerations for aSCROLL_NOTIFY ClientMessage

enum WBScrollEventParam
{
  WB_SCROLL_DEFAULT = 0,    
  WB_SCROLL_HORIZONTAL = 1, 
  WB_SCROLL_VERTICAL = 2,   

  WB_SCROLL_KNOB = 0,       
  WB_SCROLL_FORWARD = 1,    
  WB_SCROLL_BACKWARD = -1,  
  WB_SCROLL_PAGEFWD = 2,    
  WB_SCROLL_PAGEBACK = -2,  
  WB_SCROLL_FIRST = -3,     
  WB_SCROLL_LAST = 3,       

  WB_SCROLL_DBLCLICK = 4,   

  WB_SCROLL_ABSOLUTE = 99,  
  WB_SCROLL_RELATIVE = -99, 

  WB_SCROLL_NA = 0x80000000 
};







//    ____  ___   ____   _____       _     ____  ___   //
//   / ___|/ _ \ |  _ \ | ____|     / \   |  _ \|_ _|  //
//  | |   | | | || |_) ||  _|      / _ \  | |_) || |   //
//  | |___| |_| ||  _ < | |___    / ___ \ |  __/ | |   //
//   \____|\___/ |_| \_\|_____|  /_/   \_\|_|   |___|  //
//                                                     //

#define WB_STANDARD_INPUT_MASK (FocusChangeMask | PropertyChangeMask | ExposureMask | StructureNotifyMask | VisibilityChangeMask | SubstructureNotifyMask)

#define WB_KEYBOARD_INPUT_MASK (KeyPressMask | KeyReleaseMask)

#define WB_MOUSE_INPUT_MASK (ButtonPressMask | ButtonReleaseMask | PointerMotionMask | EnterWindowMask | LeaveWindowMask)


enum WMPropertiesWindowType
{
  // must be ONLY ONE of the items below
  WMPropertiesWindowType_TypeMask     = 0x3f,
  WMPropertiesWindowType_Normal       = 0,
  WMPropertiesWindowType_Desktop      = 1,
  WMPropertiesWindowType_Dock         = 2,
  WMPropertiesWindowType_ToolBar      = 3,
  WMPropertiesWindowType_Menu         = 4,
  WMPropertiesWindowType_Utility      = 5,
  WMPropertiesWindowType_Splash       = 6,
  WMPropertiesWindowType_Dialog       = 7,
  WMPropertiesWindowType_DropDownMenu = 8,
  WMPropertiesWindowType_PopupMenu    = 9,
  WMPropertiesWindowType_ToolTip      = 10,
  WMPropertiesWindowType_Notification = 11,
  WMPropertiesWindowType_Combo        = 12,
  WMPropertiesWindowType_Drag_N_Drop  = 13,
  WMPropertiesWindowType_Reserved14   = 14,
  WMPropertiesWindowType_Reserved15   = 15,


  // may be A COMBINATION of the items below
  WMPropertiesWindowType_StateMask        = 0xfffC0,

  WMPropertiesWindowType_NoState          = 0,
  WMPropertiesWindowType_Modal            = 0x00040,
  WMPropertiesWindowType_Sticky           = 0x00080,
  WMPropertiesWindowType_VMax             = 0x00100,
  WMPropertiesWindowType_HMax             = 0x00200,
  WMPropertiesWindowType_FullScreen       = 0x00400,
  WMPropertiesWindowType_Hidden           = 0x00800,
  WMPropertiesWindowType_Shaded           = 0x01000,
  WMPropertiesWindowType_SkipTaskbar      = 0x02000,
  WMPropertiesWindowType_SkipPager        = 0x04000,
  WMPropertiesWindowType_Above            = 0x08000,
  WMPropertiesWindowType_Below            = 0x10000,
  WMPropertiesWindowType_Focused          = 0x20000,
  WMPropertiesWindowType_DemandsAttention = 0x40000,
  WMPropertiesWindowType_Reserved80000    = 0x80000,


  // TODO:  other stuff

  WMPropertiesWindowType_Max = 0x80000000
};

enum WMPropertiesWMProtocols
{
  // The following flags indicate WM_PROTOCOLS support
  // Assigning these directly can have unexpected consequences
  WMPropertiesWMProtocols_Mask            = 0xff,
  WMPropertiesWMProtocols_None            = 0x0,  
  WMPropertiesWMProtocols_DeleteWindow    = 0x01,
  WMPropertiesWMProtocols_Reserved2       = 0x02,
  WMPropertiesWMProtocols_Reserved3       = 0x04,
  WMPropertiesWMProtocols_Reserved4       = 0x08,
  WMPropertiesWMProtocols_Reserved5       = 0x10,
  WMPropertiesWMProtocols_Reserved6       = 0x20,
  WMPropertiesWMProtocols_Reserved7       = 0x40,
  WMPropertiesWMProtocols_Reserved8       = 0x80,
};

enum WBCreateWindow_flags
{
  // The following flags indicate WM_PROTOCOLS support
  // Assigning these directly can have unexpected consequences
  WBCreateWindow_flagsDefault             = 0, 
#if defined(__DOXYGEN__) || defined(HAS_WB_UINT64_BUILTIN)
  WBCreateWindow_flagsNoImageCache      = 0x100000000LL,  
#endif // HAS_WB_UINT64_BUILTIN
};

// TODO:  equivalents for when WBUINT64 is NOT supported as a native 'long long' data type (rare, if ever)


Window WBCreateWindow(Display *pDisplay, Window wIDParent,
                      WBWinEvent pProc, const char *szClass,
                      int iX, int iY, int iWidth, int iHeight, int iBorder, int iIO,
                      WB_UINT64 iFlags, XSetWindowAttributes *pXSWA);

void WBDestroyWindow(Window wID);

Window WBGetApplicationWindow(void);

void WBSetApplicationWindow(Window wID);

int WBDefault(Window wID, XEvent *pEvent);

int WBAppDefault(XEvent *pEvent);

void WBRegisterAppCallback(WBAppEvent pCallback);

void WBUnregisterAppCallback();

void WBRegisterWindowCallback(Window wID, WBWinEvent pCallback);

void WBUnregisterWindowCallback(Window wID);

void WBSetWindowTitle(Window wID, const char *szTitle);

void WBSetWMProperties(Window wID, const char *szTitle, XSizeHints *pNormalHints,
                       XWMHints *pWMHints, XClassHint *pClassHints);
void WBSetWMPropertiesWindowType(Window wID, enum WMPropertiesWindowType wmProp);

void WBChangeWMPropertiesWindowType(Window wID, enum WMPropertiesWindowType wmPropSet, enum WMPropertiesWindowType wmChangeMask);


enum WMPropertiesWindowType WBGetWMPropertiesWindowType(Window wID);

void WBSetWMProtocols(Window wID, Atom aProperty, ...);


typedef int (*WBLocateWindowCallback)(Window wID, void *pData);

Window WBLocateWindow(WBLocateWindowCallback callback, void *pData);

void WBSetInputFocus(Window wID);

Display * WBGetWindowDisplay(Window wID);

void WBSetWindowIcon(Window wID, int idIcon);

void WBSetWindowFont(Window wID, WB_FONTC pFont);

void WBSetWindowDefaultCursor(Window wID, int idStandardCursor);

int WBGetWindowDefaultCursor(Window wID);

void WBCreateWindowDefaultGC(Window wID, unsigned long clrFG, unsigned long clrBG);

void WBSetWindowDefaultGC(Window wID, WBGC hGC);

WBGC WBGetWindowCopyGC(Window wID);

#define WBGetWindowCopyGC2(wID, gcSrc) WBCopyDrawableGC(WBGetWindowDisplay(wID), wID, gcSrc)

void WBSetWindowData(Window wID, int iIndex, void *pData);

void WBBeginWaitCursor(Window wID);

void WBEndWaitCursor(Window wID);

void WBSetWindowCursor(Window wID, int idCursor);

void WBRestoreDefaultCursor(Window wID);

WBGC WBGetWindowDefaultGC(Window wID);

WB_FONTC WBQueryWindowFont(Window wID);

WB_FONT WBGetWindowFont(Window wID);

unsigned long WBGetWindowFGColor(Window wID);

unsigned long WBGetWindowBGColor(Window wID);

void WBDefaultStandardColormap(Display *pDisplay, XStandardColormap *pMap);

void WBSetWindowClassName(Window wID, const char *szClassName);

const char *WBGetWindowClassName(Window wID);

void *WBGetWindowData(Window wID, int iIndex);

void WBGetWindowGeom(Window wID, WB_GEOM *pGeom);

void WBGetWindowGeom2(Window wID, WB_GEOM *pGeom);


void WBGetWindowGeom0(Window wID, WB_GEOM *pGeom);  // absolute window geometry (from latest notification)

void WBGetWindowRect(Window wID, WB_RECT *pRect);

void WBGetClientRect(Window wID, WB_RECT *pRect);


Window WBGetParentWindow(Window wID);


void WBSetParentWindow(Window wID, Window wIDParent);

int WBReparentWindow(Window wID, Window wIDParent, int iX, int iY); // keeps internal info up to date

int WBIsChildWindow(Window wIDParent, Window wIDChild);  // non-zero if 'wIDParent' is in a parent relationship with 'wIDChild'

#define WBPointInRect(X,Y,R) ((X) >= (R).left && (X) < (R).right && (Y) >= (R).top && (Y) < (R).bottom)

#define WBPointInGeom(X,Y,G) ((X) >= (G).x && (X) < ((G).x + (G).width) && (Y) >= (G).y && (Y) < ((G).y + (G).height))

#define WBRectOverlapped(R1,R2) \
  ((((R1).left >= (R2).left && (R1).left < (R2).right) || \
    ((R2).left >= (R1).left && (R2).left < (R1).right)) && \
   (((R1).top >= (R2).top && (R1).top < (R2).bottom) || \
    ((R2).top >= (R1).top && (R2).top < (R1).bottom)))

#define WBGeomOverlapped(G1,G2) \
  ((((G1).x >= (G2).x && (G1).x < (G2).x + (G2).width) || \
    ((G2).x >= (G1).x && (G2).x < (G1).x + (G1).width)) && \
   (((G1).y >= (G2).y && (G1).y < (G2).y + (G2).height) || \
    ((G2).y >= (G1).y && (G2).y < (G1).y + (G1).height)))

void WBXlatCoordPoint(Window wIDSrc, int iXSrc, int iYSrc, Window wIDDest, int *piXDest, int *piYDest);

void WBXlatCoordGeom(Window wIDSrc, const WB_GEOM *pGeomSrc, Window wIDDest, WB_GEOM *pGeomDest);

void WBXlatCoordRect(Window wIDSrc, const WB_RECT *pRectSrc, Window wIDDest, WB_RECT *pRectDest);

int WBPointInWindow(Window wIDRef, int iX, int iY, Window wIDQuery);

// keyboard translation helpers

#define WB_KEYEVENT_KEYSYM 8 /* bit flags for 'piAltCtrlShift' below */

#define WB_KEYEVENT_ALT    4

#define WB_KEYEVENT_CTRL   2

#define WB_KEYEVENT_SHIFT  1

#define WB_KEYEVENT_ACSMASK 7


int WBKeyEventProcessKey(const XKeyEvent *pEvent, char *pBuf, int *pcbLen, int *piAltCtrlShift);
  // NOTE:  WB_CHAR notification messages (related to WBKeyEventProcessKey)
  // message_type == aWB_CHAR
  // data.l[0] is return frmo WBKeyEventProcessKey
  // data.l[1] is *piAltCtrlShift from WBKeyEventProcessKey
  // data.l[2] is number of characters decoded into data.l[3..4]
  // data.l[3..4] (as char[]) is decode buffer (at least 8 chars long, possibly 16 for 64-bit)



// pointer event definitions - WB_POINTER
// data.l[0] is notification code (below)
// data.l[1] is bitmap of mouse button state (button 1 is bit 0, button 2 is bit 1, etc.)
// data.l[2] is 'WB_KEYEVENT_' mask for CTRL+ALT+SHIFT
// data.l[3] is translated X coordinate
// data.l[4] is translated Y coordinate

#define WB_POINTER_UNSPECIFIED 0 /* possible motion or state-change notifications */

#define WB_POINTER_CLICK       1

#define WB_POINTER_DBLCLICK    2

#define WB_POINTER_DRAG        3 /* window proc returns window ID to support drag/drop */

#define WB_POINTER_DROP        4 /* may not happen if drag is canceled */

#define WB_POINTER_MOVE        5 /* motion notify while dragging */

#define WB_POINTER_CANCEL      6 /* reservedly any kind of cancellation, but for now, 'drag cancel' */

#define WB_POINTER_SCROLLUP    7 /* scroll event, mouse button 4 */

#define WB_POINTER_SCROLLDOWN  8 /* scroll event, mouse button 5 */

#define WB_POINTER_BUTTON1 1 /* these are bitmasks */

#define WB_POINTER_BUTTON2 2

#define WB_POINTER_BUTTON3 4

#define WB_POINTER_BUTTON4 8

#define WB_POINTER_BUTTON5 16

void WBRegisterMenuCallback(Window wID, WBWinEvent pCallback);

void WBAddMenuWindow(Window wID, Window wIDMenu);
Window WBGetMenuWindow(Window wID);  // returns ID of menu window assigned by above (one only)
void WBRemoveMenuWindow(Window wID, Window wIDMenu);

int WBIsValid(Display *pDisplay, Window wID);



//   _____ __     __ _____  _   _  _____  ____    //
//  | ____|\ \   / /| ____|| \ | ||_   _|/ ___|   //
//  |  _|   \ \ / / |  _|  |  \| |  | |  \___ \   //
//  | |___   \ V /  | |___ | |\  |  | |   ___) |  //
//  |_____|   \_/   |_____||_| \_|  |_|  |____/   //
//                                                //

// message loop helpers

Time WBGetLastEventTime(void);


int WBCheckGetEvent(Display *pDisplay, XEvent *pEvent);

void WBWaitForEvent(Display *pDisplay);


void WBDispatch(XEvent *pEvent);

int WBAppDispatch(XEvent *pEvent);

int WBWindowDispatch(Window wID, XEvent *pEvent);

const char * WBEventName(int iEventID);

int WBShowModal(Window wID, int bMenuSplashFlag);  // modal window - returns 'EndModal' value or -1 on error

void WBEndModal(Window wID, int iReturn);

// client-side message queue (avoids XSendEvent)
// to send a message directly use WBAppDispatch and WBWindowDispatch

int WBNextEvent(Display *pDisplay, XEvent *pEvent);

int WBPostEvent(Window wID, XEvent *pEvent);

int WBPostPriorityEvent(Window wID, XEvent *pEvent); // like above but it goes at the beginning of the queue

void WBPostDelayedEvent(XEvent *pEvent, unsigned int nDelay);

int WBPostAppEvent(XEvent *pEvent);

void WBPostDelayedSetFocusAppEvent(Display *pDisplay, Window wID, Window wIDFrom, unsigned int nDelay);

void WBProcessExposeEvent(XExposeEvent *pEvent);  // paint optimization



//                                                                          //
//            _   _  ___   _   _        _                                   //
//           | | | ||_ _| | | | |  ___ | | _ __    ___  _ __  ___           //
//           | | | | | |  | |_| | / _ \| || '_ \  / _ \| '__|/ __|          //
//           | |_| | | |  |  _  ||  __/| || |_) ||  __/| |   \__ \          //
//            \___/ |___| |_| |_| \___||_|| .__/  \___||_|   |___/          //
//                                        |_|                               //
//                                                                          //


void WBMouseCancel(Display *pDisplay, Window wID);




//    ____ _     ___ ____  ____   ___    _    ____  ____     //
//   / ___| |   |_ _|  _ \| __ ) / _ \  / \  |  _ \|  _ \    //
//  | |   | |    | || |_) |  _ \| | | |/ _ \ | |_) | | | |   //
//  | |___| |___ | ||  __/| |_) | |_| / ___ \|  _ <| |_| |   //
//   \____|_____|___|_|   |____/ \___/_/   \_\_| \_\____/    //
//                                                           //

void * WBGetClipboardData(Display *pDisplay, Atom *paType, int *piFormat, unsigned long *pnData);

int WBSetClipboardData(Display *pDisplay, Atom aType, int iFormat, const void *pData, unsigned long nData);


// lower level functions for 'Selections'

void * WBGetSelectionData(Display *pDisplay, Atom aSelection, Atom *paType, int *piFormat, unsigned long *pnData);


int WBSetSelectionData(Display *pDisplay, Atom aSelection, Atom aType, int iFormat, const void *pData, unsigned long nData);




//   _____ __  __ ____    ___   ____   _   _  ____   _____   //
//  | ____|\ \/ /|  _ \  / _ \ / ___| | | | ||  _ \ | ____|  //
//  |  _|   \  / | |_) || | | |\___ \ | | | || |_) ||  _|    //
//  | |___  /  \ |  __/ | |_| | ___) || |_| ||  _ < | |___   //
//  |_____|/_/\_\|_|     \___/ |____/  \___/ |_| \_\|_____|  //
//                                                           //

int WBMapWindow(Display *pDisplay, Window wID);
int WBMapRaised(Display *pDisplay, Window wID);
int WBUnmapWindow(Display *pDisplay, Window wID);

int WBIsMapped(Display *pDisplay, Window wID);  // non-zero if mapped, zero otherwise
  // NOTE:  this only works for windows that have been registered with a callback


// paint helpers (working in conjunction with 'WBProcessExposeEvent')

void WBInvalidateGeom(Window wID, const WB_GEOM *pGeom, int bPaintFlag);
void WBInvalidateRegion(Window wID, Region rgn, int bPaintFlag);
void WBValidateGeom(Window wID, const WB_GEOM *pGeom);
void WBValidateRegion(Window wID, Region rgn);

Region WBGetInvalidRegion(Window wID);

Region WBGetPaintRegion(Window wID);

Region WBRectToRegion(const WB_RECT *pRect);

Region WBGeomToRegion(const WB_GEOM *pGeom);

Region WBCopyRegion(Region rgnSource);

void WBUpdateWindow(Window wID);  // posts an expose event for the specified window

void WBUpdateWindowImmediately(Window wID);  // sends expose event synchronously (can cause recursion)

WBGC WBBeginPaint(Window wID, XExposeEvent *pEvent, WB_GEOM *pgRet); // WBGC has invalid region assigned

WBGC WBBeginPaintGeom(Window wID, WB_GEOM *pgBounds); // WBGC has invalid region assigned

void WBEndPaint(Window wID, WBGC gc);  // frees the 'paint WBGC' and also resets the invalid region

void WBClearWindow(Window wID, WBGC gc);


// RECT versions (as inline)

#if defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)
static __inline__ void WBInvalidateRect(Window wID, const WB_RECT *pRCT, int bPaintFlag)
{
  WB_GEOM geom;

  if(!pRCT)
  {
    WBInvalidateGeom(wID, NULL, bPaintFlag);
    return;
  }

  geom.x      = pRCT->left;
  geom.y      = pRCT->top;
  geom.width  = pRCT->right - pRCT->left;
  geom.height = pRCT->bottom - pRCT->top;
  geom.border = 0;

  WBInvalidateGeom(wID, &geom, bPaintFlag);
}
#else // defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)
void WBInvalidateRect(Window wID, const WB_RECT *pRCT, int bPaintFlag);
#endif // defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)

#if defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)
static __inline__ void WBValidateRect(Window wID, WB_RECT *pRCT)
{
  WB_GEOM geom;

  if(!pRCT)
  {
    WBValidateGeom(wID, NULL);
    return;
  }

  geom.x      = pRCT->left;
  geom.y      = pRCT->top;
  geom.width  = pRCT->right - pRCT->left;
  geom.height = pRCT->bottom - pRCT->top;
  geom.border = 0;

  WBValidateGeom(wID, &geom);
}
#else // defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)
void WBValidateRect(Window wID, WB_RECT *pRCT);
#endif // defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)


//    ____                     _      _               ____               _               _     //
//   / ___| _ __  __ _  _ __  | |__  (_)  ___  ___   / ___| ___   _ __  | |_  ___ __  __| |_   //
//  | |  _ | '__|/ _` || '_ \ | '_ \ | | / __|/ __| | |    / _ \ | '_ \ | __|/ _ \\ \/ /| __|  //
//  | |_| || |  | (_| || |_) || | | || || (__ \__ \ | |___| (_) || | | || |_|  __/ >  < | |_   //
//   \____||_|   \__,_|| .__/ |_| |_||_| \___||___/  \____|\___/ |_| |_| \__|\___|/_/\_\ \__|  //
//                     |_|                                                                     //

WBGC WBCreateGC(Display *pDisplay, Drawable dw, unsigned long valuemask,
                const XGCValues *values);

int WBChangeGC(WBGC hGC, unsigned long valuemask,
               const XGCValues *values);

Status WBGetGCValues(WBGC hGC, unsigned long valuemask,
                     XGCValues *values);

unsigned long WBGetGCBGColor(WBGC gc);

unsigned long WBGetGCFGColor(WBGC gc);

WB_FONTC WBQueryGCFont(WBGC gc);

WB_FONT WBGetGCFont(Display *pDisplay, WBGC gc);

WBGC WBCopyGC(WBGC hGCOrig);

int WBCopyGC2(WBGC hGCOrig, unsigned long valuemask, WBGC hGCDest);

WBGC WBCopyDrawableGC(Display *pDisplay, Drawable dw, WBGC hGCOrig);

void WBFreeGC(WBGC hGC);

GContext WBGContextFromGC(WBGC hGC);

int WBSetRegion(WBGC hGC, Region rgnClip);

int WBSetClipOrigin(WBGC hGC, int clip_x_origin, int clip_y_origin);

int WBSetClipMask(WBGC hGC, Pixmap pixmap);

int WBSetFunction(WBGC hGC, int function);

#if defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)
static __inline__ unsigned long WBGetForeground(WBGC hGC) { return hGC->values.foreground; }
#else // defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)
#define WBGetForeground(X) ((X)->values.foreground)
#endif // defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)

int WBSetForeground(WBGC hGC, unsigned long foreground);

#if defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)
static __inline__ unsigned long WBGetBackground(WBGC hGC) { return hGC->values.background; }
#else // defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)
#define WBGetBackground(X) ((X)->values.background)
#endif // defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)

int WBSetBackground(WBGC hGC, unsigned long background);

int WBSetFont(WBGC hGC, WB_FONTC pFont);

int WBSetFontNoCopy(WBGC hGC, WB_FONT pFont);

int WBSetLineAttributes(WBGC hGC, unsigned int line_width,
                        int line_style, int cap_style, int join_style);

int WBSetDashes(WBGC hGC, int dash_offset, const char dash_list[], int n);



//   ___                               ____           _            //
//  |_ _|_ __ ___   __ _  __ _  ___   / ___|__ _  ___| |__   ___   //
//   | || '_ ` _ \ / _` |/ _` |/ _ \ | |   / _` |/ __| '_ \ / _ \  //
//   | || | | | | | (_| | (_| |  __/ | |__| (_| | (__| | | |  __/  //
//  |___|_| |_| |_|\__,_|\__, |\___|  \____\__,_|\___|_| |_|\___|  //
//                       |___/                                     //
//                                                                 //


XImage *WBGetWindowImage(Display *pDisplay, Window wID);

int WBAssignWindowImage(Display *pDisplay, Window wID, XImage *pImage);

int WBCopyIntoWindowImage(Display *pDisplay, Window wID, XImage *pSrcImage,
                          int xSrc, int ySrc, int width, int height,
                          int xOffs, int yOffs);

void WBUpdateWindowWithImage(Display *pDisplay, Window wID);



//    ____                     _      _              _   _        _                           //
//   / ___| _ __  __ _  _ __  | |__  (_)  ___  ___  | | | |  ___ | | _ __    ___  _ __  ___   //
//  | |  _ | '__|/ _` || '_ \ | '_ \ | | / __|/ __| | |_| | / _ \| || '_ \  / _ \| '__|/ __|  //
//  | |_| || |  | (_| || |_) || | | || || (__ \__ \ |  _  ||  __/| || |_) ||  __/| |   \__ \  //
//   \____||_|   \__,_|| .__/ |_| |_||_| \___||___/ |_| |_| \___||_|| .__/  \___||_|   |___/  //
//                     |_|                                          |_|                       //
//                                                                                            //
//  Wrapper functions for X11 'primitive' operations that can use a window's cached XImage    //
//                                                                                            //


int WBDrawPoint(Display *display, Drawable d, WBGC gc, int x, int y);


int WBDrawPoints(Display *display, Drawable d, WBGC gc, XPoint *points,
                 int npoints, int mode);


int WBDrawLine(Display *display, Drawable d, WBGC gc,
               int x1, int y1, int x2, int y2);


int WBDrawLines(Display *display, Drawable d, WBGC gc, XPoint *points,
                int npoints, int mode);


int WBDrawRectangle(Display *display, Drawable d, WBGC gc, int x, int y,
                    unsigned int width, unsigned int height);


int WBFillRectangle(Display *display, Drawable d, WBGC gc, int x, int y,
                    unsigned int width, unsigned int height);


int WBDrawArc(Display *display, Drawable d, WBGC gc, int x, int y,
              unsigned int width, unsigned int height,
              int angle1, int angle2);


int WBFillArc(Display *display, Drawable d, WBGC gc, int x, int y,
              unsigned int width, unsigned int height,
              int angle1, int angle2);


int WBFillPolygon(Display *display, Drawable d, WBGC gc, XPoint *points,
                  int npoints, int shape, int mode);


int WBDrawString(Display *display, Drawable d, WBGC gc, int x, int y,
                 const char *string, int length);



//   _____  ___  __  __  _____  ____   ____    //
//  |_   _||_ _||  \/  || ____||  _ \ / ___|   //
//    | |   | | | |\/| ||  _|  | |_) |\___ \   //
//    | |   | | | |  | || |___ |  _ <  ___) |  //
//    |_|  |___||_|  |_||_____||_| \_\|____/   //
//                                             //

int CreateTimer(Display *pDisplay, Window wID, unsigned long lInterval, long lID, int iPeriodic);
  // NOTE:  'iPeriodic' non-zero for periodic, zero for one-shot.  'lInterval' is in microseconds
  //        Assign 'lID' to a unique value for the specified pDisplay and wID

void DeleteTimer(Display *pDisplay, Window wID, long lID);  // deletes entry with matching Display, Window, ID



// ****************************************************
//
//            E R R O R   H A N D L I N G
//
// ****************************************************

typedef struct s_WB_ERROR_INFO
{
  Display *pDisplay;     
  const char *pFunc;     
  int iLine;             
  unsigned long serial;  
  int error_code;        
  int request_code;      
  int minor_code;        
  XID resourceid;        
} WB_ERROR_INFO;



#if defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)
static __inline__ void WBSupressErrorOutput(void)
{
extern int bIgnoreXErrors;

  // TODO:  serialize this with a mutex or other sync object?
  bIgnoreXErrors++;
}
#else // defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)
void WBSupressErrorOutput(void);
#endif // defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)

#if defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)
static __inline__ void WBAllowErrorOutput(void)
{
extern int bIgnoreXErrors;

  // TODO:  serialize this with a mutex or other sync object?
  if(bIgnoreXErrors > 0)
  {
    bIgnoreXErrors--;
  }
  else
  {
    bIgnoreXErrors = 0;
  }
}
#else // defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)
void WBAllowErrorOutput(void);
#endif // defined(__DOXYGEN__) || defined(__GNUC__) || defined(_MSVC_VER)


void WBErrorClear(void);

int WBErrorCheck(void);

int WBErrorCheckRetry(void);

const WB_ERROR_INFO * WBGetLastError(void);



#ifdef __cplusplus
};
#endif // __cplusplus

#endif // WINDOW_HELPER_H_INCLUDED