X11workbench Toolkit  1.0
conf_help.h
Go to the documentation of this file.
1 // __ _ _ _ //
3 // ___ ___ _ __ / _| | |__ ___ | | _ __ | |__ //
4 // / __|/ _ \ | '_ \ | |_ | '_ \ / _ \| || '_ \ | '_ \ //
5 // | (__| (_) || | | || _| | | | || __/| || |_) |_| | | | //
6 // \___|\___/ |_| |_||_|_____|_| |_| \___||_|| .__/(_)_| |_| //
7 // |_____| |_| //
8 // //
9 // helper API for 'conf' files (global and per-user) //
10 // //
12 
13 /*****************************************************************************
14 
15  X11workbench - X11 programmer's 'work bench' application and toolkit
16  Copyright (c) 2010-2019 by Bob Frazier (aka 'Big Bad Bombastic Bob')
17 
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  MIT-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  MIT-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 // conf file format:
51 // [section header]
52 // data identifier=data value
53 
79 #ifndef CONF_HELPER_H_INCLUDED
80 #define CONF_HELPER_H_INCLUDED
81 
82 #include "platform_helper.h" /* this also includes the X11 headers */
83 
84 #ifdef __cplusplus
85 extern "C" {
86 #endif // __cplusplus
87 
88 
89 #ifndef GLOBAL_PATH /* this can be defined by the config script */
90 #warning "GLOBAL_PATH not defined, assuming /usr/local/etc"
91 #define GLOBAL_PATH "/usr/local/etc"
92 #endif // GLOBAL_PATH
93 
94 #ifndef GLOBAL_XPATH /* this can be defined by the config script */
95 #ifdef __FreeBSD__
96 #warning "GLOBAL_XPATH not defined, assuming /usr/local/etc/X11"
97 #define GLOBAL_XPATH "/usr/local/etc/X11"
98 #else // others whose distros don't consider 'X11' to be in '/usr/local'
99 #warning "GLOBAL_XPATH not defined, assuming /etc/X11"
100 #define GLOBAL_XPATH "/etc/X11"
101 #endif // __FreeBSD__, others
102 #endif // GLOBAL_XPATH
103 
104 
106 // LOCAL_PATH definition - this has changed a bit
107 // the new standard for config files is:
108 //
109 // ~/.config/application/whatever
110 // ~/.local/share/application/whatever
111 //
112 // the old standard was ~/.application/whatever
113 //
114 #define LOCAL_PATH "~/.local/share/" /* the normal path for application-local files - was '~/' */
115 #define CONFIG_PATH "~/.config/" /* alternate path for config files */
116 //#define LOCAL_PATH "~/"
117 #define LOCAL_CONF_NAME "settings"
118 /* local conf name will be ~/.local/share/appname/settings.conf, or if that is not possible, ~/appname.conf */
119 
120 #define CH_OPEN_TIMEOUT 5000 /* wait up to 5000 milliseconds before timing out */
121 
122 
126 #define CH_FLAGS_DEFAULT 0
127 #define CH_FLAGS_GLOBAL 0x1
128 #define CH_FLAGS_WRITE 0x2
130 #define CHPARSEXML_DEFAULT 0
131 #define CHPARSEXML_PAREN 1
132 #define CHPARSEXML_BRACKET 2
149 void CHRegisterArgs(int argc, char **argv); // call in 'main'
150 
158 void CHOnExit(void);
159 
169 const char * const *CHGetArgV(void);
170 
180 int CHGetArgC(void);
181 
196 int CHGetResourceString(Display *pDisplay,const char *szIdentifier, char *szData, int cbData);
197 
210 int CHGetResourceInt(Display *pDisplay,const char *szIdentifier);
211 
212 
213 
215 // configuration file management
217 
232 void * CHOpenConfFile(const char *szAppName, int iFlags);
233 
245 void CHCloseConfFile(void * hFile);
246 
257 void CHDestroyConfFile(void * hFile);
258 
275 int CHGetConfFileString(void * hFile, const char *szSection,
276  const char *szIdentifier, char *szData, int cbData);
277 
292 int CHWriteConfFileString(void * hFile, const char *szSection,
293  const char *szIdentifier, const char *szData);
294 
295 
311 int CHGetConfFileInt(void * hFile, const char *szSection, const char *szIdentifier);
312 
327 int CHWriteConfFileInt(void * hFile, const char *szSection, const char *szIdentifier, int iData);
328 
329 
330 
331 // XSETTINGS
332 
343 void CHSettingsRefresh(Display *pDisplay); // call this to re-read and re-build XSettings info
344 
345 // X11 settings collection
346 
351 {
355 };
356 
357 
382 typedef struct tagXSETTINGS_DATA_COLOR // also used internally by XSettings
383 {
384  unsigned short sRed;
385  unsigned short sBlue;
386  unsigned short sGreen;
387  unsigned short sAlpha;
389 
390 
423 typedef struct tagCHXSetting
424 {
425  const char *szName;
426  int iType;
427  int iLen;
428  unsigned int uiSerial;
429  union
430  {
431  int iData;
434  void *pData;
435  char *szData;
436  } uData;
438 
439 
465 typedef struct tagCHXSettings
466 {
467  Display *pDisplay;
468  int nSettings;
469  unsigned int uiSerial;
471 } CHXSettings;
472 
473 
483 const CHXSettings * CHGetXSettings(Display *pDisplay);
484 
496 const CHXSetting * CHGetXSetting(Display *pDisplay, const char *szSettingName);
497 
498 
509 int CHGetDoubleClickTime(Display *pDisplay);
510 
521 int CHGetDoubleClickDistance(Display *pDisplay);
522 
533 int CHGetDragThreshold(Display *pDisplay);
534 
545 int CHGetCursorBlink(Display *pDisplay);
546 
557 int CHGetCursorBlinkTime(Display *pDisplay);
558 
559 
561 // _ //
562 // ___ ___ | | ___ _ __ ___ //
563 // / __/ _ \| |/ _ \| '__/ __| //
564 // | (_| (_) | | (_) | | \__ \ //
565 // \___\___/|_|\___/|_| |___/ //
566 // //
568 
579 const char *CHGetBorderColor(Display *pDisplay);
580 
592 const char *CHGetStaticBackgroundColor(Display *pDisplay);
593 
604 const char *CHGetToolTipBackgroundColor(Display *pDisplay);
605 
617 const char *CHGetDialogBackgroundColor(Display *pDisplay);
618 
630 const char *CHGetActiveBackgroundColor(Display *pDisplay);
631 
643 const char *CHGetDisabledBackgroundColor(Display *pDisplay);
644 
656 const char *CHGetBackgroundColor(Display *pDisplay);
657 
669 const char *CHGetDialogTextColor(Display *pDisplay);
670 
682 const char *CHGetActiveTextColor(Display *pDisplay);
683 
695 const char *CHGetDisabledTextColor(Display *pDisplay);
696 
707 const char *CHGetToolTipTextColor(Display *pDisplay);
708 
720 const char *CHGetTextColor(Display *pDisplay);
721 
733 const char *CHGetHighlightForegroundColor(Display *pDisplay);
734 
746 const char *CHGetHighlightBackgroundColor(Display *pDisplay);
747 
748 
749 
750 // XML help
751 
794 typedef struct tagCHXMLEntry
795 {
799 
802 
803 } CHXMLEntry;
804 
855 CHXMLEntry *CHParseXML(const char *pXMLData, int cbLength);
856 
866 void CHDebugDumpXML(CHXMLEntry *pEntry); // dumps XML using debug I/O functions
867 
882 char *CHParseXMLTagContents(const char *pTagContents, int cbLength);
883 
917 const char *CHFindNextXMLTag(const char *pTagContents, int cbLength, int nNestingFlags);
918 
941 const char *CHFindEndOfXMLTag(const char *pTagContents, int cbLength);
942 
943 
970 const char *CHFindEndOfXMLSection(const char *pTagContents, int cbLength, char cEndChar, int bUseQuotes);
971 
972 
973 // MIME type help
974 
986 char *CHGetFileMimeType(const char *szFileName);
987 
1002 char *CHGetMimeDefaultApp(const char *szMimeType);
1003 
1016 char *CHGetDesktopFileInfo(const char *szDesktopFile, const char *szInfo);
1017 
1018 
1019 
1020 // debug
1021 #ifndef NO_DEBUG
1022 
1030 void CHDumpConfig(void);
1031 
1032 #endif // NO_DEBUG
1033 
1034 #ifdef __cplusplus
1035 };
1036 #endif // __cplusplus
1037 
1038 
1039 #endif // CONF_HELPER_H_INCLUDED
1040 
const char * CHGetHighlightForegroundColor(Display *pDisplay)
returns highlight foreground color
Definition: conf_help.c:3409
char * CHGetMimeDefaultApp(const char *szMimeType)
Get the default application for a particular MIME type.
Definition: conf_help.c:3110
char * szData
'char' typed pointer to data within string area
Definition: conf_help.h:435
const CHXSettings * CHGetXSettings(Display *pDisplay)
returns a pointer to the cached X settings
int CHGetDoubleClickDistance(Display *pDisplay)
returns default double click distance (from X settings)
Definition: conf_help.c:2241
int iContentsIndex
0-based first array index for 'contents' for this entry; <= 0 for none
Definition: conf_help.h:798
unsigned short sBlue
16-bit RGB value for Blue
Definition: conf_help.h:385
int nDataOffset
BYTE offset to data (zero-byte-terminated) string (from beginning of array) for the entry data; <= 0 ...
Definition: conf_help.h:801
int iContainer
0-based index for container; <= 0 for none.
Definition: conf_help.h:797
const CHXSetting * CHGetXSetting(Display *pDisplay, const char *szSettingName)
returns a pointer to a specific X setting entry by name
Definition: conf_help.c:1746
XSETTINGS_DATA_COLOR clrData
The data as a color value.
Definition: conf_help.h:433
void CHOnExit(void)
frees resources used by Configuration 'helper' functions
Definition: conf_help.c:166
const char * CHFindEndOfXMLTag(const char *pTagContents, int cbLength)
Parses contents of an XML tag to find the end of it.
Definition: conf_help.c:3077
const char * CHGetActiveBackgroundColor(Display *pDisplay)
returns background color for active elements
Definition: conf_help.c:3323
const char * CHGetStaticBackgroundColor(Display *pDisplay)
returns background color for static elements
Definition: conf_help.c:3288
Array wrapper for CHXSetting cache.
Definition: conf_help.h:465
CHXSetting aData[1]
An array of 'nSettings' CHXSetting structures. Binary and string data directly follows the array.
Definition: conf_help.h:470
struct tagXSETTINGS_DATA_COLOR XSETTINGS_DATA_COLOR
Structure for storing configuration color information, XSettingsTypeColor.
void * CHOpenConfFile(const char *szAppName, int iFlags)
open configuration file for read/write, optionally creating it, based on application name
Definition: conf_help.c:643
const char * CHFindEndOfXMLSection(const char *pTagContents, int cbLength, char cEndChar, int bUseQuotes)
Parses XML text for the end of a 'section', typically ending in '>' ')' or ']'.
Definition: conf_help.c:2941
int CHGetConfFileString(void *hFile, const char *szSection, const char *szIdentifier, char *szData, int cbData)
obtain a string from a configuration file
Definition: conf_help.c:1242
unsigned int uiSerial
serial number from last XSETTINGS query
Definition: conf_help.h:469
const char * CHGetActiveTextColor(Display *pDisplay)
returns 'active' text color
Definition: conf_help.c:3366
void * pData
un-typed pointer to data within string area
Definition: conf_help.h:434
int CHGetCursorBlinkTime(Display *pDisplay)
returns default cursor blink time (from X settings)
Definition: conf_help.c:2358
int iType
The setting type (XSettingsType enumeration)
Definition: conf_help.h:426
const char * CHFindNextXMLTag(const char *pTagContents, int cbLength, int nNestingFlags)
Parses contents of a XML to find the next tag, skipping comments along the way.
Definition: conf_help.c:2889
const char * CHGetDisabledTextColor(Display *pDisplay)
returns 'disabled' (greyed) text color
Definition: conf_help.c:3378
int CHGetArgC(void)
retrieves the argument count stored by CHRegisterArgs()
Definition: conf_help.c:630
struct tagCHXSettings CHXSettings
Array wrapper for CHXSetting cache.
int CHGetResourceString(Display *pDisplay, const char *szIdentifier, char *szData, int cbData)
Queries desktop resource strings (may become deprecated)
Definition: conf_help.c:474
WB_INT64 llData
Reserved element, forces 64-bit size.
Definition: conf_help.h:432
int CHWriteConfFileString(void *hFile, const char *szSection, const char *szIdentifier, const char *szData)
write a string to a configuration file
Definition: conf_help.c:1376
int nLabelOffset
BYTE offset to label (zero-byte-terminated) string (from beginning of array) for this entry; <= 0 for...
Definition: conf_help.h:800
void CHCloseConfFile(void *hFile)
close configuration file opened by CHOpenConfFile(), but does NOT free memory resources
Definition: conf_help.c:850
const char * CHGetTextColor(Display *pDisplay)
returns text color
Definition: conf_help.c:3399
const char * CHGetDialogTextColor(Display *pDisplay)
returns text color for dialog frame elements
Definition: conf_help.c:3352
int CHGetResourceInt(Display *pDisplay, const char *szIdentifier)
Queryies desktop resource integer values (from strings) (may become deprecated)
Definition: conf_help.c:604
CHXMLEntry * CHParseXML(const char *pXMLData, int cbLength)
Parses contents of an XML tag, returning as WBAlloc'd string list similar to environment strings.
Definition: conf_help.c:2465
void CHDumpConfig(void)
dump config information using debug output functions
Definition: conf_help.c:3444
int iData
The data as an integer value.
Definition: conf_help.h:431
const char * CHGetHighlightBackgroundColor(Display *pDisplay)
returns highlight background color
Definition: conf_help.c:3425
const char * CHGetDialogBackgroundColor(Display *pDisplay)
returns background color for dialog frame elements
Definition: conf_help.c:3308
const char * szName
pointer to the NAME string within memory that follows CHXSettings::aData
Definition: conf_help.h:425
int CHGetDoubleClickTime(Display *pDisplay)
returns default double click time (from X settings)
Definition: conf_help.c:2202
The setting is an RGBA Color stored as XSETTINGS_DATA_COLOR.
Definition: conf_help.h:354
int CHGetCursorBlink(Display *pDisplay)
returns default cursor blink 'enable' flag (from X settings)
Definition: conf_help.c:2319
int iLen
length (where applicable)
Definition: conf_help.h:427
int CHWriteConfFileInt(void *hFile, const char *szSection, const char *szIdentifier, int iData)
write an integer value to a configuration file
Definition: conf_help.c:1662
unsigned short sAlpha
16-bit ALPHA value. If not used, it will be 0xffff
Definition: conf_help.h:387
Display * pDisplay
identifies which display it belongs to (reserved)
Definition: conf_help.h:467
Descriptor for parsed XML entry.
Definition: conf_help.h:794
void CHSettingsRefresh(Display *pDisplay)
refresh the internally cached X settings
Definition: conf_help.c:1798
int CHGetConfFileInt(void *hFile, const char *szSection, const char *szIdentifier)
obtain an integer value from a configuration file
Definition: conf_help.c:1640
#define __PACKED__
PACKED definition.
char * CHGetFileMimeType(const char *szFileName)
Get the MIME type for a particular file name or extension.
Definition: conf_help.c:3088
The setting is an integer.
Definition: conf_help.h:352
long long WB_INT64
Platform abstract 64-bit integer.
unsigned short sGreen
16-bit RGB value for Green
Definition: conf_help.h:386
const char * CHGetDisabledBackgroundColor(Display *pDisplay)
returns background color for disabled (greyed) elements
Definition: conf_help.c:3336
const char * CHGetToolTipTextColor(Display *pDisplay)
returns text color for 'tool tips'
Definition: conf_help.c:3390
const char * CHGetBackgroundColor(Display *pDisplay)
returns background color for non-static elements
Definition: conf_help.c:3341
int CHGetDragThreshold(Display *pDisplay)
returns default drag threshold (from X settings)
Definition: conf_help.c:2280
int iNextIndex
0-based index for next item at this level; <= 0 for none. 0 marks "end of list" for top level
Definition: conf_help.h:796
const char *const * CHGetArgV(void)
retrieves the array of arguments stored by CHRegisterArgs()
Definition: conf_help.c:635
void CHDebugDumpXML(CHXMLEntry *pEntry)
Parses contents of an XML tag, returning as WBAlloc'd string list similar to environment strings.
union tagCHXSetting::@7 uData
union of the data alias'
Definition file for platform-specific utility functions.
void CHDestroyConfFile(void *hFile)
destroy configuration file opened by CHOpenConfFile(), freeing memory resources (but not the files)
Definition: conf_help.c:882
The setting is a 0-byte terminated ASCII string.
Definition: conf_help.h:353
int nSettings
the total number of settings in aData
Definition: conf_help.h:468
unsigned int uiSerial
serial # from last XSETTINGS [endian-ized]
Definition: conf_help.h:428
struct tagCHXMLEntry CHXMLEntry
Descriptor for parsed XML entry.
char * CHGetDesktopFileInfo(const char *szDesktopFile, const char *szInfo)
Get the default application for a particular MIME type.
Definition: conf_help.c:3158
const char * CHGetBorderColor(Display *pDisplay)
returns border color
Definition: conf_help.c:3279
Structure for storing configuration color information, XSettingsTypeColor.
Definition: conf_help.h:382
unsigned short sRed
16-bit RGB value for RED
Definition: conf_help.h:384
XSettingsType
Enumeration for 'XSettingsType' which describes the type of setting being cached.
Definition: conf_help.h:350
struct tagCHXSetting CHXSetting
Structure for storing settings information internally.
char * CHParseXMLTagContents(const char *pTagContents, int cbLength)
Parses contents of a single XML tag, returning as WBAlloc'd string list similar to environment string...
Definition: conf_help.c:2600
Structure for storing settings information internally.
Definition: conf_help.h:423
const char * CHGetToolTipBackgroundColor(Display *pDisplay)
returns background color for 'tool tips'
Definition: conf_help.c:3299