X11 Work Bench 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-2016 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 
114 #define DIALOG_WINDOW_TAG (*((const unsigned int *)"DLGW"))
115 #define DIALOG_ENTRY_TAG (*((const unsigned int *)"DLGE"))
154 typedef struct __WB_DIALOG_ENTRY__
155 {
156  unsigned int ulTag;
157  Window wID;
158  Atom aClass;
159  int iID;
160  int iFlags;
161  int iX,
162  iY,
163  iWidth,
164  iHeight;
165 
166 } WBDialogEntry;
167 
168 
205 typedef struct __WB_DIALOG_WINDOW__
206 {
207  unsigned int ulTag;
208  Window wID;
209  Window wIDOwner;
210  void *pUserData;
211  int iFlags;
212  int iClientX,
213  iClientY,
214  iClientWidth,
215  iClientHeight;
216  XColor clrFG,
217  clrBG,
218  clrBD;
220 
227 {
261 
266  WBDialogWindow_MAX = 0x80000000L
267 };
268 
275 {
280 
281 // TODO: other user-definable flags
282 
283 
284 // the remaining bits are reserved for internal use
285 
286  // TODO: others
287 
288  // alignment flags - these match the 'CONTROL_' bit flags in dialgo_controls.h
289 
290  WBDialogEntry_HResize = 0x00040000,
291  WBDialogEntry_VResize = 0x00080000,
293 
295  WBDialogEntry_VAlignTop = 0x00100000,
299 
305  WBDialogEntry_AlignMask = 0x00f00000,
306 
307 
311  WBDialogEntry_PRESSED = 0x08000000,
312 
313  // focus and 'default' flags
314 
316  WBDialogEntry_HAS_FOCUS = 0x20000000,
318  WBDialogEntry_DEFAULT = 0x80000000
319 
320 };
321 
360 WBDialogWindow *DLGCreateDialogWindow(const char *szTitle, const char *szDialogResource,
361  int iX, int iY, int iWidth, int iHeight,
362  WBWinEvent pUserCallback, int iFlags,
363  void *pUserData);
364 
374 void DLGAssignOwner(WBDialogWindow *pDlg, Window wIDOwner);
375 
384 void DLGRecalcLayout(Window wID); // recalculate layout information (propagates to children)
385 
393 int DLGPixelHeight(WBDialogWindow *pDlg, int iHeight); // pixel height from dialog units
394 
402 int DLGPixelWidth(WBDialogWindow *pDlg, int iWidth); // pixel width from dialog units
403 
404 
417 void DLGSetUserCallback(WBDialogWindow *pDLG, WBWinEvent pCallBack);
418  // assigns the user-defined callback function (one only). Not all messages pass through the callback
419 
429 int DLGProcessHotKey(WBDialogWindow *pDLG, XEvent *pEvent);
430  // returns non-zero value if hot-key was processed and no further event processing
431  // should be performed. Otherwise returns zero. Default dialog callback handles this
432  // automatically (as does the default dialog control callback, when applicable).
433 
434 
442 static __inline__ WBDialogWindow *DLGGetDialogWindowStruct(Window wID) // for dialog windows, returns WBDialogWindow struct
443 {
444  WBDialogWindow *pRval = (WBDialogWindow *)WBGetWindowData(wID, 0); // offset 0 for window-specific structs
445 
446  if(pRval && DIALOG_WINDOW_TAG == pRval->ulTag)
447  {
448  return(pRval);
449  }
450 
451 // if(pRval && pRval->ulTag != DIALOG_WINDOW_TAG)
452 // {
453 // WB_ERROR_PRINT("ERROR: DLGGetDialogWindowStruct, bad tag: %08xH %08xH\n", DIALOG_WINDOW_TAG, pRval->ulTag);
454 // }
455 // else // if(!pRval)
456 // {
457 // WB_ERROR_PRINT("ERROR: DLGGetDialogWindowStruct - pointer is NULL\n");
458 // }
459 
460  return(NULL);
461 }
462 
472 void * DLGGetDialogWindowUserData(Window wID);
473 
482 void DLGDestroyDialogWindow(Window wID);
483 
493 void DLGDestroyDialogWindow2(WBDialogWindow *pDialogWindow);
494 
495 
496 
497 // control query and enumeration
498 
506 Window DLGGetDialogControl(WBDialogWindow *pDialog, int iControlID); // returns first match
507 
518 WBDialogEntry *DLGGetDialogControlEntry(WBDialogWindow *pDialog, Window idControl); // returns matching WBDialogEntry
519 
530 Window DLGGetFirstDialogControl(WBDialogWindow *pDialog); // first dialog control in tab order
542 Window DLGGetNextDialogControl(WBDialogWindow *pDialog, Window idControl); // control following wIDControl
543 
555 Window DLGGetPrevDialogControl(WBDialogWindow *pDialog, Window idControl); // control prior to wIDControl
556  // NOTE: 'GetNext' and 'GetPrev' wrap around and may return the same window ID
557 
558 
559 // POSTING AND SENDING NOTIFICATION MESSAGES
560 
571 static __inline__ void DLGNotifyDlg(WBDialogWindow *pDLG, Atom aNotify,
572  long lData0, long lData1, long lData2, long lData3, long lData4)
573 {
574 Display *pDisplay = WBGetWindowDisplay(pDLG->wID);
575 
576  XClientMessageEvent evt = {
577  .type=ClientMessage,
578  .serial=0,
579  .send_event=0,
580  .display=pDisplay,
581  .window=pDLG->wID,
582  .message_type=aNotify,
583  .format=32
584  };
585  evt.data.l[0] = lData0;
586  evt.data.l[1] = lData1;
587  evt.data.l[2] = lData2;
588  evt.data.l[3] = lData3;
589  evt.data.l[4] = lData4;
590 
591  WBWindowDispatch(pDLG->wID, (XEvent *)&evt);
592 }
593 
594 
606 static __inline__ void DLGNotifyDlgAsync(WBDialogWindow *pDLG, Atom aNotify,
607  long lData0, long lData1, long lData2, long lData3, long lData4)
608 {
609 Display *pDisplay = WBGetWindowDisplay(pDLG->wID);
610 
611  XClientMessageEvent evt = {
612  .type=ClientMessage,
613  .serial=0,
614  .send_event=0,
615  .display=pDisplay,
616  .window=pDLG->wID,
617  .message_type=aNotify,
618  .format=32
619  };
620  evt.data.l[0] = lData0;
621  evt.data.l[1] = lData1;
622  evt.data.l[2] = lData2;
623  evt.data.l[3] = lData3;
624  evt.data.l[4] = lData4;
625 
626  WBPostPriorityEvent(pDLG->wID, (XEvent *)&evt);
627 }
628 
629 
630 
631 // special pre-defined dialog windows
632 
650 {
668 
670 
671  // 'or' with one or more button types (none implies 'ok' by itself)
672  // NOTE: left-right ordering by numeric value (lowest is left-most)
673 
675 
676  MessageBox_OK = 0x20,
677  MessageBox_Yes = 0x40,
678  MessageBox_No = 0x80,
683 
684  // legal multi-bit combinations
690 
692 };
693 
708 int DLGMessageBox(int iType, Window wIDOwner, const char *szTitle, const char *szMessage);
709 
727 char *DLGInputBox(Window wIDOwner, const char *szTitle, const char *szPrompt, const char *szDefault,
728  int iWidth, int iMaxChar);
729 
730 
740 {
746 
747  // modifications
753 
755 };
756 
789 char *DLGFileDialog(int iType, Window wIDOwner, const char *szDefPath, const char *szDefName,
790  const char *szExtAndDescList);
791 
792 
809 void DLGSplashScreen(char * aXPM[], const char *szCopyright, unsigned long clrText);
810 
811 
812 #ifdef __cplusplus
813 };
814 #endif // __cplusplus
815 
816 
817 #endif // DIALOG_WINDOW_H_INCLUDED
818 
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.
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
'window helper' main header file for the X11workbench Toolkit API
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.
WBDialogEntryFlags
enumeration for the iFlags member of WBDialogEntry
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.
MessageBoxEnum
Message Box flag enumeration.
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'
Modifier Flag - No 'Folder Navigation'.
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>
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.
FileDialogEnum
FileDialog enumeration.
Icon - white thumb up on green square.
mask for icon bits
Icon - white &#39;middle finger&#39; on red triangle.
Horizontal Resize flag.
Application Window flag.
#define DIALOG_WINDOW_TAG
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; ...
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.
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
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
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)
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)
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:962
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) ...
re-alignment with respect to center (as a percentage, stretching allowed)
vertical alignment mask
Type Flag - File Open Dialog.
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:1063
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 ...
Icon - exclamation point on yellow triangle.
resize maintains position/size with respect to left
Visibility flag.
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.
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
horizontal alignment mask
alignment mask (both horizontal and vertical)
dialog box flag, can be resized horizontally
Icon - white thumb down on red square.
Button Bits - Abort button.
unsigned int ulTag
tag word, always assigned to DIALOG_ENTRY_TAG
Icon - yellow circle with white exclamation point.
Button Bits - OK button plus Cancel button.
Atom aClass
control class identifier
int iFlags
visibility, focus, etc.
Type Flag - Folder Dialog.