X11workbench Toolkit  1.0
dialog_window.h
Go to the documentation of this file.
1 // _ _ _ _ _ _ //
3 // __| |(_) __ _ | | ___ __ _ __ __(_) _ __ __| | ___ __ __| |__ //
4 // / _` || | / _` || | / _ \ / _` | \ \ /\ / /| || '_ \ / _` | / _ \\ \ /\ / /| '_ \ //
5 // | (_| || || (_| || || (_) || (_| | \ V V / | || | | || (_| || (_) |\ V V /_| | | | //
6 // \__,_||_| \__,_||_| \___/ \__, |_____\_/\_/ |_||_| |_| \__,_| \___/ \_/\_/(_)_| |_| //
7 // |___/|_____| //
8 // //
9 // modal or modeless window based on a dialog template //
10 // //
12 
13 /*****************************************************************************
14 
15  X11workbench - X11 programmer's 'work bench' application and toolkit
16  Copyright (c) 2010-2018 by Bob Frazier (aka 'Big Bad Bombastic Bob')
17  all rights reserved
18 
19  DISCLAIMER: The X11workbench application and toolkit software are supplied
20  'as-is', with no warranties, either implied or explicit.
21  Any claims to alleged functionality or features should be
22  considered 'preliminary', and might not function as advertised.
23 
24  BSD-like license:
25 
26  There is no restriction as to what you can do with this software, so long
27  as you include the above copyright notice and DISCLAIMER for any distributed
28  work that is equal to or derived from this one, along with this paragraph
29  that explains the terms of the license if the source is also being made
30  available. A "derived work" describes a work that uses a significant portion
31  of the source files or algorithms that are included with this one.
32  Specifically excluded from this are files that were generated by the software,
33  or anything that is included with the software that is part of another package
34  (such as files that were created or added during the 'configure' process).
35  Specifically included is the use of part or all of any of the X11 workbench
36  toolkit source or header files in your distributed application. If you do not
37  ship the source, the above copyright statement is still required to be placed
38  in a reasonably prominent place, such as documentation, splash screens, and/or
39  'about the application' dialog boxes.
40 
41  Use and distribution are in accordance with GPL, LGPL, and/or the above
42  BSD-like license. See COPYING and README files for more information.
43 
44 
45  Additional information at http://sourceforge.net/projects/X11workbench
46 
47 ******************************************************************************/
48 
49 
50 #ifndef DIALOG_WINDOW_H_INCLUDED
51 #define DIALOG_WINDOW_H_INCLUDED
52 
53 #include "window_helper.h"
54 
55 #ifdef __cplusplus
56 extern "C" {
57 #endif // __cplusplus
58 
59 
165 #define DIALOG_WINDOW_TAG (*((const unsigned int *)"DLGW"))
166 #define DIALOG_ENTRY_TAG (*((const unsigned int *)"DLGE"))
205 typedef struct __WB_DIALOG_ENTRY__
206 {
207  unsigned int ulTag;
208  Window wID;
209  Atom aClass;
210  int iID;
211  int iFlags;
212  int iX,
213  iY,
214  iWidth,
215  iHeight;
216 
217 } WBDialogEntry;
218 
219 
256 typedef struct __WB_DIALOG_WINDOW__
257 {
258  unsigned int ulTag;
259  Window wID;
260  Window wIDOwner;
261  void *pUserData;
262  int iFlags;
263  int iClientX,
264  iClientY,
265  iClientWidth,
266  iClientHeight;
267  XColor clrFG,
268  clrBG,
269  clrBD;
271 
278 {
312 
317  WBDialogWindow_MAX = 0x80000000L
318 };
319 
326 {
327  WBDialogEntry_VISIBLE = 0x00000001,
328  WBDialogEntry_EDIT = 0x00000002,
329  WBDialogEntry_MULTILINE = 0x00000004,
330  WBDialogEntry_ALLCHARS = 0x00000008,
331 
332  WBDialogEntry_TRISTATE = 0x00000010,
333  WBDialogEntry_CHECKED = 0x00000020,
334  WBDialogEntry_NO_BORDER = 0x00000040,
335 
336  // text alignment (in caption or body of control, when applicable)
346 
347 
348 // TODO: other user-definable flags
349 
350 
351 // the remaining bits are reserved for internal use
352 
353  // TODO: others
354 
355  // control alignment flags - these match the 'CONTROL_' bit flags in dialog_controls.h
356 
357  WBDialogEntry_HResize = 0x00040000,
358  WBDialogEntry_VResize = 0x00080000,
360 
362  WBDialogEntry_VAlignTop = 0x00100000,
366 
372  WBDialogEntry_AlignMask = 0x00f00000,
373 
374 
377  WBDialogEntry_DISABLED = 0x04000000,
378  WBDialogEntry_PRESSED = 0x08000000,
379 
380  // focus and 'default' flags
381 
383  WBDialogEntry_HAS_FOCUS = 0x20000000,
385  WBDialogEntry_DEFAULT = 0x80000000
386 
387 };
388 
427 WBDialogWindow *DLGCreateDialogWindow(const char *szTitle, const char *szDialogResource,
428  int iX, int iY, int iWidth, int iHeight,
429  WBWinEvent pUserCallback, int iFlags,
430  void *pUserData);
431 
441 void DLGAssignOwner(WBDialogWindow *pDlg, Window wIDOwner);
442 
451 void DLGRecalcLayout(Window wID); // recalculate layout information (propagates to children)
452 
460 int DLGPixelHeight(WBDialogWindow *pDlg, int iHeight); // pixel height from dialog units
461 
469 int DLGPixelWidth(WBDialogWindow *pDlg, int iWidth); // pixel width from dialog units
470 
471 
484 void DLGSetUserCallback(WBDialogWindow *pDLG, WBWinEvent pCallBack);
485  // assigns the user-defined callback function (one only). Not all messages pass through the callback
486 
496 int DLGProcessHotKey(WBDialogWindow *pDLG, XEvent *pEvent);
497  // returns non-zero value if hot-key was processed and no further event processing
498  // should be performed. Otherwise returns zero. Default dialog callback handles this
499  // automatically (as does the default dialog control callback, when applicable).
500 
501 
509 static __inline__ WBDialogWindow *DLGGetDialogWindowStruct(Window wID) // for dialog windows, returns WBDialogWindow struct
510 {
511  WBDialogWindow *pRval = (WBDialogWindow *)WBGetWindowData(wID, 0); // offset 0 for window-specific structs
512 
513  if(pRval && DIALOG_WINDOW_TAG == pRval->ulTag)
514  {
515  return(pRval);
516  }
517 
518 // if(pRval && pRval->ulTag != DIALOG_WINDOW_TAG)
519 // {
520 // WB_ERROR_PRINT("ERROR: DLGGetDialogWindowStruct, bad tag: %08xH %08xH\n", DIALOG_WINDOW_TAG, pRval->ulTag);
521 // }
522 // else // if(!pRval)
523 // {
524 // WB_ERROR_PRINT("ERROR: DLGGetDialogWindowStruct - pointer is NULL\n");
525 // }
526 
527  return(NULL);
528 }
529 
539 void * DLGGetDialogWindowUserData(Window wID);
540 
549 void DLGDestroyDialogWindow(Window wID);
550 
560 void DLGDestroyDialogWindow2(WBDialogWindow *pDialogWindow);
561 
562 
563 
564 // control query and enumeration
565 
573 Window DLGGetDialogControl(WBDialogWindow *pDialog, int iControlID); // returns first match
574 
585 WBDialogEntry *DLGGetDialogControlEntry(WBDialogWindow *pDialog, Window idControl); // returns matching WBDialogEntry
586 
597 Window DLGGetFirstDialogControl(WBDialogWindow *pDialog); // first dialog control in tab order
609 Window DLGGetNextDialogControl(WBDialogWindow *pDialog, Window idControl); // control following wIDControl
610 
622 Window DLGGetPrevDialogControl(WBDialogWindow *pDialog, Window idControl); // control prior to wIDControl
623  // NOTE: 'GetNext' and 'GetPrev' wrap around and may return the same window ID
624 
625 
626 // POSTING AND SENDING NOTIFICATION MESSAGES
627 
638 static __inline__ void DLGNotifyDlg(WBDialogWindow *pDLG, Atom aNotify,
639  long lData0, long lData1, long lData2, long lData3, long lData4)
640 {
641 Display *pDisplay = WBGetWindowDisplay(pDLG->wID);
642 
643  XClientMessageEvent evt = {
644  .type=ClientMessage,
645  .serial=0,
646  .send_event=0,
647  .display=pDisplay,
648  .window=pDLG->wID,
649  .message_type=aNotify,
650  .format=32
651  };
652  evt.data.l[0] = lData0;
653  evt.data.l[1] = lData1;
654  evt.data.l[2] = lData2;
655  evt.data.l[3] = lData3;
656  evt.data.l[4] = lData4;
657 
658  WBWindowDispatch(pDLG->wID, (XEvent *)&evt);
659 }
660 
661 
673 static __inline__ void DLGNotifyDlgAsync(WBDialogWindow *pDLG, Atom aNotify,
674  long lData0, long lData1, long lData2, long lData3, long lData4)
675 {
676 Display *pDisplay = WBGetWindowDisplay(pDLG->wID);
677 
678  XClientMessageEvent evt = {
679  .type=ClientMessage,
680  .serial=0,
681  .send_event=0,
682  .display=pDisplay,
683  .window=pDLG->wID,
684  .message_type=aNotify,
685  .format=32
686  };
687  evt.data.l[0] = lData0;
688  evt.data.l[1] = lData1;
689  evt.data.l[2] = lData2;
690  evt.data.l[3] = lData3;
691  evt.data.l[4] = lData4;
692 
693  WBPostPriorityEvent(pDLG->wID, (XEvent *)&evt);
694 }
695 
696 
697 
698 // special pre-defined dialog windows
699 
717 {
735 
737 
738  // 'or' with one or more button types (none implies 'ok' by itself)
739  // NOTE: left-right ordering by numeric value (lowest is left-most)
740 
742 
743  MessageBox_OK = 0x20,
744  MessageBox_Yes = 0x40,
745  MessageBox_No = 0x80,
750 
751  // legal multi-bit combinations
757 
759 };
760 
775 int DLGMessageBox(int iType, Window wIDOwner, const char *szTitle, const char *szMessage);
776 
794 char *DLGInputBox(Window wIDOwner, const char *szTitle, const char *szPrompt, const char *szDefault,
795  int iWidth, int iMaxChar);
796 
797 
807 {
813 
814  // modifications
820 
822 };
823 
856 char *DLGFileDialog(int iType, Window wIDOwner, const char *szDefPath, const char *szDefName,
857  const char *szExtAndDescList);
858 
859 
876 int DLGColorDialog(Window wIDOwner, XStandardColormap *pColorMap, XColor *pColor);
877 
878 
895 XFontSet DLGFontDialog(Display *pDisplay, Window wIDOwner, XFontSet fsDefault);
896 
897 
914 void DLGSplashScreen(char * aXPM[], const char *szCopyright, unsigned long clrText);
915 
916 
917 #ifdef __cplusplus
918 };
919 #endif // __cplusplus
920 
921 
922 #endif // DIALOG_WINDOW_H_INCLUDED
923 
bit mask for modifier flag
Icon - multiple question marks in red triangle.
void * DLGGetDialogWindowUserData(Window wID)
Returns a pointer to the dialog window's 'user data' assigned at create time.
'window helper' main header file for the X11workbench Toolkit API
Horizontal text alignment bits.
Button Bits - default button (currently 'OK')
Modifier Flag - simple 'file name input'.
set for "default" controls
int iClientWidth
width of the dialog window's client area
WBDialogWindowFlags
enumeration for the iFlags member of WBDialogWindow
void * WBGetWindowData(Window wID, int iIndex)
Gets the data associated with this window and the specified index.
struct __WB_DIALOG_WINDOW__ WBDialogWindow
Structure identifying a dialog (frame) window.
XFontSet DLGFontDialog(Display *pDisplay, Window wIDOwner, XFontSet fsDefault)
Display a modal Font Dialog window, returning the selected font in the XColor structure pointed to by...
Definition: dialog_impl.c:1927
WBDialogWindow * DLGCreateDialogWindow(const char *szTitle, const char *szDialogResource, int iX, int iY, int iWidth, int iHeight, WBWinEvent pUserCallback, int iFlags, void *pUserData)
create a dialog window using a text resource
unsigned int ulTag
tag word, always assigned to DIALOG_WINDOW_TAG
Icon - black question mark in yellow triangle.
Icon - white skull and crossbones on black square.
static __inline__ void DLGNotifyDlg(WBDialogWindow *pDLG, Atom aNotify, long lData0, long lData1, long lData2, long lData3, long lData4)
Notify dialog window by calling the window's own callback function directly with an event...
Icon - white question mark in green triangle.
Button Bits - Cancel button.
Button Bits - Abort button plus Retry button.
XColor clrBD
border pixel color
Modifier Flag - No 'Overwrite Prompt' if overwriting.
for pushbuttons, causes it to be drawn 'pressed'
int DLGColorDialog(Window wIDOwner, XStandardColormap *pColorMap, XColor *pColor)
Display a modal Color Dialog window, returning the selected color in the XColor structure pointed to ...
Definition: dialog_impl.c:1805
Modifier Flag - No 'Folder Navigation'.
MessageBoxEnum
Message Box flag enumeration.
char * DLGInputBox(Window wIDOwner, const char *szTitle, const char *szPrompt, const char *szDefault, int iWidth, int iMaxChar)
Displays a special purpose dialog window that retrieves a character string as input.
Definition: dialog_impl.c:558
Icon - white asterisk on blue circle.
Window DLGGetNextDialogControl(WBDialogWindow *pDialog, Window idControl)
Return the Window ID of the NEXT dialog control within the 'tab order', based on the specified contro...
int WBWindowDispatch(Window wID, XEvent *pEvent)
Dispatches a window XEvent. May be called directly.
Auto-center mouse pointer.
default position re-alignment with respect to center (as a percentage, no stretching) ...
Icon - yellow triangle (nothing else)
user-editable text
Button Bits - No button.
int DLGPixelHeight(WBDialogWindow *pDlg, int iHeight)
Height of a single dialog unit (in pixels)
Button Bits - Yes button plus No button and Cancel button.
Modifier Flag - No Overwrite.
Button Bits - Yes button plus No button.
int WBPostPriorityEvent(Window wID, XEvent *pEvent)
Places a copy of the specified event at the end of the priority (internal) event queue.
Button Bits - OK button.
mask for button bits
Button Bits - Yes button.
Window DLGGetFirstDialogControl(WBDialogWindow *pDialog)
Return the Window ID of the FIRST dialog control within the 'tab order'.
for edit controls, prevents trapping <ENTER>
Horizontally align text center.
Horizontally align text right.
WBDialogEntryFlags
enumeration for the iFlags member of WBDialogEntry
prevents trapping <ESC> <ENTER> and anything else
Icon - white fright mask on black circle.
Window wID
window ID of control
Icon - green circle.
bit mask for type flag
default position re-alignment with respect to center (as a percentage, no stretching) ...
Icon - red stop sign.
Icon - white thumb up on green square.
mask for icon bits
#define DIALOG_WINDOW_TAG
Icon - white &#39;middle finger&#39; on red triangle.
Horizontal Resize flag.
Application Window flag.
&#39;checked&#39; state
static __inline__ void DLGNotifyDlgAsync(WBDialogWindow *pDLG, Atom aNotify, long lData0, long lData1, long lData2, long lData3, long lData4)
Notify dialog window by posting an event that will ASYNCHRONOUSLY be sent to the dialog window&#39;s call...
Modifier Flag - Read Only.
dialog box flag, can be resized vertically
Type Flag - File Save As Dialog.
re-alignment with respect to center (as a percentage, stretching allowed)
Window DLGGetDialogControl(WBDialogWindow *pDialog, int iControlID)
returns the Window ID of a member control of the dialog window using the &#39;control ID&#39; ...
void DLGSplashScreen(char *aXPM[], const char *szCopyright, unsigned long clrText)
Display a splash screen for 5 seconds (with animation and copyright string), and then return...
Definition: dialog_impl.c:1969
int DLGProcessHotKey(WBDialogWindow *pDLG, XEvent *pEvent)
return non-zero if a hot-key was processed and no further processing should be done. Otherwise returns zero.
All text alignment bits.
int iClientY
vertical position of upper left corner of client area, relative to the window
resize maintains position/size with respect to bottom
void DLGSetUserCallback(WBDialogWindow *pDLG, WBWinEvent pCallBack)
Assign the callback function for a dialog window.
Window wID
window ID of the dialog (frame) window
Button Bits - Retry button.
XColor clrBG
background pixel color
causes the control to be drawn &#39;disabled&#39; and NOT be selectable for focus
Window wIDOwner
window ID of the dialog&#39;s OWNER (can be &#39;None&#39;, should be assigned for Modal dialogs) ...
Icon - brown and tan teddy bear on grey circle.
int iFlags
bitmask of attribute flags (see &#39;WBDialogWindowFlags&#39; enumeration)
Vertically align text center (default)
MAX flag (reserved)
struct __WB_DIALOG_ENTRY__ WBDialogEntry
Structure identifying one of the controls that appears on a dialog window.
void * pUserData
user data that&#39;s assignable via API
int DLGPixelWidth(WBDialogWindow *pDlg, int iWidth)
Width of a single dialog unit (in pixels)
set for &#39;pushbuttons&#39; (which override &#39;default&#39; for <ENTER>)
XColor clrFG
foreground pixel color
void DLGDestroyDialogWindow(Window wID)
Destroy a modeless dialog window via its window ID.
resize mask for dialog box
int(* WBWinEvent)(Window wID, XEvent *pEvent)
event callback function type for window events
Vertical Resize flag.
Structure identifying one of the controls that appears on a dialog window.
void DLGAssignOwner(WBDialogWindow *pDlg, Window wIDOwner)
Assign owning window to dialog.
Icon - purple T-Rex head on white circle (more like mozilla)
void DLGDestroyDialogWindow2(WBDialogWindow *pDialogWindow)
Destroy a modeless dialog window via a pointer to its WBDialogWindow structure.
resize maintains position/size with respect to top
int iY
vertical position of upper left corner of control (client-relative)
Display * WBGetWindowDisplay(Window wID)
returns the Display associated with a window
Button Bits - Ignore button.
static __inline__ WBDialogWindow * DLGGetDialogWindowStruct(Window wID)
Returns a pointer to the dialog window&#39;s WBDialogWindow structure.
set when item gets focus. cleared when no focus
Type Flag - File Save Dialog.
resize maintains position/size with respect to right
int iID
control unique identifier (number or atom, as appropriate, unique to dialog window) ...
&#39;no border&#39; flag (don&#39;t display a border - statics, typically)
re-alignment with respect to center (as a percentage, stretching allowed)
vertical alignment mask
Type Flag - File Open Dialog.
Horizontally align text left (default)
Window DLGGetPrevDialogControl(WBDialogWindow *pDialog, Window idControl)
Return the Window ID of the PREVIOUS dialog control within the &#39;tab order&#39;, based on the specified co...
int iClientX
horizontal position of upper left corner of client area, relative to the window
Structure identifying a dialog (frame) window.
Icon - application icon (from icon_app.xpm)
WBDialogEntry * DLGGetDialogControlEntry(WBDialogWindow *pDialog, Window idControl)
returns a pointer to the WBDialogEntry for a member control using the control&#39;s Window ID ...
Vertically align text top.
Icon - exclamation point on yellow triangle.
resize maintains position/size with respect to left
Visibility flag.
char * DLGFileDialog(int iType, Window wIDOwner, const char *szDefPath, const char *szDefName, const char *szExtAndDescList)
Display a modal File Dialog window, returning a WBAlloc&#39;d pointer to a null-byte terminated string co...
Definition: dialog_impl.c:964
Button Bits - Abort button plus Retry button and Ignore button.
int iClientHeight
height of the dialog window&#39;s client area
set when item CAN have focus.
void DLGRecalcLayout(Window wID)
Force re-calculation of dialog window (and control) layout.
horizontal alignment mask
Vertical text alignment bits.
alignment mask (both horizontal and vertical)
dialog box flag, can be resized horizontally
Icon - white thumb down on red square.
Vertically align text bottom.
Button Bits - Abort button.
unsigned int ulTag
tag word, always assigned to DIALOG_ENTRY_TAG
FileDialogEnum
FileDialog enumeration.
Icon - yellow circle with white exclamation point.
Button Bits - OK button plus Cancel button.
int DLGMessageBox(int iType, Window wIDOwner, const char *szTitle, const char *szMessage)
Display a modal &#39;message box&#39; dialog window with a specific title, message, and button combination...
Definition: dialog_impl.c:231
Atom aClass
control class identifier
&#39;tri-stated&#39; state (overrides &#39;checked&#39; state)
int iFlags
visibility, focus, etc.
Type Flag - Folder Dialog.