WINGs/WINGs/WUtil.h

   1 /* WUtil.h
   2  *
   3  *  Copyright (c) 1998 scottc
   4  *  Copyright (c) 1999-2004 Dan Pascu
   5  *  Copyright (c) 1999-2000 Alfredo K. Kojima
   6  *
   7  *  This program is free software; you can redistribute it and/or modify
   8  *  it under the terms of the GNU General Public License as published by
   9  *  the Free Software Foundation; either version 2 of the License, or
  10  *  (at your option) any later version.
  11  *
  12  *  This program is distributed in the hope that it will be useful,
  13  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  *  GNU General Public License for more details.
  16  *
  17  *  You should have received a copy of the GNU General Public License along
  18  *  with this program; if not, write to the Free Software Foundation, Inc.,
  19  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  20  */
  21
  22 #ifndef _WUTIL_H_
  23 #define _WUTIL_H_
  24
  25 #include <X11/Xlib.h>
  26 #include <limits.h>
  27 #include <sys/types.h>
  28
  29 /* SunOS 4.x Blargh.... */
  30 #ifndef NULL
  31 #define NULL ((void*)0)
  32 #endif
  33
  34
  35 #ifndef WMAX
  36 # define WMAX(a,b)      ((a)>(b) ? (a) : (b))
  37 #endif
  38 #ifndef WMIN
  39 # define WMIN(a,b)      ((a)<(b) ? (a) : (b))
  40 #endif
  41
  42
  43 #ifndef __ASSERT_FUNCTION
  44 # if (!defined (__GNUC__) || (__GNUC__ < 2 && \
  45       __GNUC_MINOR__ < (defined (__cplusplus) ? 6 : 4)))
  46 #  define __ASSERT_FUNCTION       ((char *) 0)
  47 # else
  48 #  define __ASSERT_FUNCTION       __PRETTY_FUNCTION__
  49 # endif
  50 #endif
  51
  52 #ifndef __GNUC__
  53 #define  __attribute__(x)  /*NOTHING*/
  54 #endif
  55
  56 #ifdef NDEBUG
  57
  58 #define wassertr(expr)          {}
  59 #define wassertrv(expr, val)    {}
  60
  61 #else /* !NDEBUG */
  62
  63 #ifdef DEBUG
  64
  65 #include <assert.h>
  66
  67 #define wassertr(expr)  assert(expr)
  68
  69 #define wassertrv(expr, val)    assert(expr)
  70
  71 #else /* !DEBUG */
  72
  73 #define wassertr(expr) \
  74     if (!(expr)) { \
  75         wwarning("%s line %i (%s): assertion %s failed",\
  76                  __FILE__, __LINE__, __ASSERT_FUNCTION, #expr);\
  77         return;\
  78     }
  79
  80 #define wassertrv(expr, val) \
  81     if (!(expr)) { \
  82         wwarning("%s line %i (%s): assertion %s failed",\
  83                  __FILE__, __LINE__, __ASSERT_FUNCTION, #expr);\
  84         return (val);\
  85     }
  86 #endif /* !DEBUG */
  87
  88 #endif /* !NDEBUG */
  89
  90
  91 #ifdef static_assert
  92 # define _wutil_static_assert(check, message) static_assert(check, message)
  93 #else
  94 # ifdef __STDC_VERSION__
  95 #  if __STDC_VERSION__ >= 201112L
  96 /*
  97  * Ideally, we would like to include <assert.h> to have 'static_assert'
  98  * properly defined, but as we have to be sure about portability and
  99  * because we're a public header we can't count on 'configure' to tell
 100  * us about availability, so we use the raw C11 keyword
 101  */
 102 #   define _wutil_static_assert(check, message) _Static_assert(check, message)
 103 #  else
 104 #   define _wutil_static_assert(check, message) /**/
 105 #  endif
 106 # else
 107 #  define _wutil_static_assert(check, message) /**/
 108 # endif
 109 #endif
 110
 111
 112 #ifdef __cplusplus
 113 extern "C" {
 114 #endif /* __cplusplus */
 115
 116
 117 typedef enum {
 118     WMPostWhenIdle = 1,
 119     WMPostASAP = 2,
 120     WMPostNow = 3
 121 } WMPostingStyle;
 122
 123
 124 typedef enum {
 125     WNCNone = 0,
 126     WNCOnName = 1,
 127     WNCOnSender = 2
 128 } WMNotificationCoalescing;
 129
 130
 131
 132 enum {
 133     WBNotFound = INT_MIN, /* element was not found in WMBag   */
 134     WANotFound = -1       /* element was not found in WMArray */
 135 };
 136
 137
 138 typedef struct W_Array WMArray;
 139 typedef struct W_Bag WMBag;
 140 typedef struct W_Data WMData;
 141 typedef struct W_TreeNode WMTreeNode;
 142 typedef struct W_HashTable WMHashTable;
 143 typedef struct W_UserDefaults WMUserDefaults;
 144 typedef struct W_Notification WMNotification;
 145 typedef struct W_NotificationQueue WMNotificationQueue;
 146 typedef struct W_Host WMHost;
 147 typedef struct W_Connection WMConnection;
 148 typedef struct W_PropList WMPropList;
 149
 150
 151
 152 /* Some typedefs for the handler stuff */
 153 typedef void *WMHandlerID;
 154
 155 typedef void WMCallback(void *data);
 156
 157 typedef void WMInputProc(int fd, int mask, void *clientData);
 158
 159
 160
 161 typedef int WMCompareDataProc(const void *item1, const void *item2);
 162 typedef void WMTreeWalkProc(WMTreeNode *aNode, void *data);
 163
 164 typedef void WMFreeDataProc(void *data);
 165
 166 /* Used by WMBag or WMArray for matching data */
 167 typedef int WMMatchDataProc(const void *item, const void *cdata);
 168
 169
 170
 171 typedef struct {
 172     int position;
 173     int count;
 174 } WMRange;
 175
 176
 177
 178 /* DO NOT ACCESS THE CONTENTS OF THIS STRUCT */
 179 typedef struct {
 180     void *table;
 181     void *nextItem;
 182     int index;
 183 } WMHashEnumerator;
 184
 185
 186 typedef struct {
 187     /* NULL is pointer hash */
 188     unsigned    (*hash)(const void *);
 189     /* NULL is pointer compare */
 190     Bool        (*keyIsEqual)(const void *, const void *);
 191     /* NULL does nothing */
 192     void*       (*retainKey)(const void *);
 193     /* NULL does nothing */
 194     void        (*releaseKey)(const void *);
 195 } WMHashTableCallbacks;
 196
 197
 198 typedef int WMArrayIterator;
 199 typedef void *WMBagIterator;
 200
 201
 202 typedef void WMNotificationObserverAction(void *observerData,
 203                                           WMNotification *notification);
 204
 205
 206 /* ---[ Macros ]---------------------------------------------------------- */
 207
 208 #define wlengthof(array)  \
 209         ({   \
 210                 _wutil_static_assert(sizeof(array) > sizeof(array[0]),   \
 211                                      "the macro 'wlengthof' cannot be used on pointers, only on known size arrays");   \
 212                 sizeof(array) / sizeof(array[0]);   \
 213         })
 214
 215
 216 /* ---[ WINGs/memory.c ]-------------------------------------------------- */
 217
 218 void* wmalloc(size_t size);
 219 void* wrealloc(void *ptr, size_t newsize);
 220 void wfree(void *ptr);
 221
 222 void wrelease(void *ptr);
 223 void* wretain(void *ptr);
 224
 225 typedef void waborthandler(int);
 226
 227 waborthandler* wsetabort(waborthandler* handler);
 228
 229 /* ---[ WINGs/error.c ]--------------------------------------------------- */
 230
 231 enum {
 232         WMESSAGE_TYPE_MESSAGE,
 233         WMESSAGE_TYPE_WARNING,
 234         WMESSAGE_TYPE_ERROR,
 235         WMESSAGE_TYPE_FATAL
 236 };
 237
 238 #define wmessage(fmt, args...) __wmessage( __func__, __FILE__, __LINE__, WMESSAGE_TYPE_MESSAGE, fmt, ## args)
 239 #define wwarning(fmt, args...) __wmessage( __func__, __FILE__, __LINE__, WMESSAGE_TYPE_WARNING, fmt, ## args)
 240 #define werror(fmt, args...) __wmessage( __func__, __FILE__, __LINE__, WMESSAGE_TYPE_ERROR, fmt, ## args)
 241 #define wfatal(fmt, args...) __wmessage( __func__, __FILE__, __LINE__, WMESSAGE_TYPE_FATAL, fmt, ## args)
 242
 243 void __wmessage(const char *func, const char *file, int line, int type, const char *msg, ...)
 244         __attribute__((__format__(printf,5,6)));
 245
 246 /* ---[ WINGs/findfile.c ]------------------------------------------------ */
 247
 248 /* For the 4 function below, you have to free the returned string when you no longer need it */
 249
 250 char* wfindfile(const char *paths, const char *file);
 251
 252 char* wfindfileinlist(char *const *path_list, const char *file);
 253
 254 char* wfindfileinarray(WMPropList* array, const char *file);
 255
 256 char* wexpandpath(const char *path);
 257
 258 int wcopy_file(const char *toPath, const char *srcFile, const char *destFile);
 259
 260 /* don't free the returned string */
 261 char* wgethomedir(void);
 262
 263 /* ---[ WINGs/proplist.c ]------------------------------------------------ */
 264
 265 int wmkdirhier(const char *path);
 266 int wrmdirhier(const char *path);
 267
 268 /* ---[ WINGs/string.c ]-------------------------------------------------- */
 269
 270 char *wstrdup(const char *str);
 271 char* wstrndup(const char *str, size_t len);
 272
 273 /* Concatenate str1 with str2 and return that in a newly malloc'ed string.
 274  * str1 and str2 can be any strings including static and constant strings.
 275  * str1 and str2 will not be modified.
 276  * Free the returned string when you're done with it. */
 277 char* wstrconcat(const char *str1, const char *str2);
 278
 279 /* This will append src to dst, and return dst. dst MUST be either NULL
 280  * or a string that was a result of a dynamic allocation (malloc, realloc
 281  * wmalloc, wrealloc, ...). dst CANNOT be a static or a constant string!
 282  * Modifies dst (no new string is created except if dst==NULL in which case
 283  * it is equivalent to calling wstrdup(src) ).
 284  * The returned address may be different from the original address of dst,
 285  * so always assign the returned address to avoid dangling pointers. */
 286 char* wstrappend(char *dst, const char *src);
 287
 288 size_t wstrlcpy(char *, const char *, size_t);
 289 size_t wstrlcat(char *, const char *, size_t);
 290
 291
 292 void wtokensplit(char *command, char ***argv, int *argc);
 293
 294 char* wtokennext(char *word, char **next);
 295
 296 char* wtokenjoin(char **list, int count);
 297
 298 void wtokenfree(char **tokens, int count);
 299
 300 char* wtrimspace(const char *s);
 301
 302 /* transform `s' so that the result is safe to pass to the shell as an argument.
 303  * returns a newly allocated string.
 304  * with very heavy inspirations from NetBSD's shquote(3).
 305  */
 306 char *wshellquote(const char *s);
 307
 308 /* ---[ WINGs/misc.c ]--------------------------------------------------- */
 309
 310 WMRange wmkrange(int start, int count);
 311
 312 /* An application must call this function before exiting, to let WUtil do some internal cleanup */
 313 void wutil_shutdown(void);
 314
 315
 316 /* ---[ WINGs/usleep.c ]-------------------------------------------------- */
 317
 318 void wusleep(unsigned int usec);
 319
 320 /* ---[ WINGs/handlers.c ]------------------------------------------------ */
 321
 322 /* Event handlers: timer, idle, input */
 323
 324 WMHandlerID WMAddTimerHandler(int milliseconds, WMCallback *callback,
 325                               void *cdata);
 326
 327 WMHandlerID WMAddPersistentTimerHandler(int milliseconds, WMCallback *callback,
 328                                         void *cdata);
 329
 330 void WMDeleteTimerWithClientData(void *cdata);
 331
 332 void WMDeleteTimerHandler(WMHandlerID handlerID);
 333
 334 WMHandlerID WMAddIdleHandler(WMCallback *callback, void *cdata);
 335
 336 void WMDeleteIdleHandler(WMHandlerID handlerID);
 337
 338 WMHandlerID WMAddInputHandler(int fd, int condition, WMInputProc *proc,
 339                               void *clientData);
 340
 341 void WMDeleteInputHandler(WMHandlerID handlerID);
 342
 343
 344 /* This function is used _only_ if you create a non-GUI program.
 345  * For GUI based programs use WMNextEvent()/WMHandleEvent() instead.
 346  * This function will handle all input/timer/idle events, then return.
 347  */
 348
 349 void WHandleEvents(void);
 350
 351 /* ---[ WINGs/hashtable.c ]----------------------------------------------- */
 352
 353
 354 WMHashTable* WMCreateHashTable(const WMHashTableCallbacks callbacks);
 355
 356 void WMFreeHashTable(WMHashTable *table);
 357
 358 void WMResetHashTable(WMHashTable *table);
 359
 360 unsigned WMCountHashTable(WMHashTable *table);
 361
 362 void* WMHashGet(WMHashTable *table, const void *key);
 363
 364 /* Returns True if there is a value associated with <key> in the table, in
 365  * which case <retKey> and <retItem> will contain the item's internal key
 366  * address and the item's value respectively.
 367  * If there is no value associated with <key> it will return False and in
 368  * this case <retKey> and <retItem> will be undefined.
 369  * Use this when you need to perform your own custom retain/release mechanism
 370  * which requires access to the keys too.
 371  */
 372 Bool WMHashGetItemAndKey(WMHashTable *table, const void *key,
 373                          void **retItem, void **retKey);
 374
 375 /* put data in table, replacing already existing data and returning
 376  * the old value */
 377 void* WMHashInsert(WMHashTable *table, const void *key, const void *data);
 378
 379 void WMHashRemove(WMHashTable *table, const void *key);
 380
 381 /* warning: do not manipulate the table while using the enumerator functions */
 382 WMHashEnumerator WMEnumerateHashTable(WMHashTable *table);
 383
 384 void* WMNextHashEnumeratorItem(WMHashEnumerator *enumerator);
 385
 386 void* WMNextHashEnumeratorKey(WMHashEnumerator *enumerator);
 387
 388 /* Returns True if there is a next element, in which case key and item
 389  * will contain the next element's key and value respectively.
 390  * If there is no next element available it will return False and in this
 391  * case key and item will be undefined.
 392  */
 393 Bool WMNextHashEnumeratorItemAndKey(WMHashEnumerator *enumerator,
 394                                     void **item, void **key);
 395
 396
 397
 398
 399 /* some predefined callback sets */
 400
 401 extern const WMHashTableCallbacks WMIntHashCallbacks;
 402 /* sizeof(keys) are <= sizeof(void*) */
 403
 404 extern const WMHashTableCallbacks WMStringHashCallbacks;
 405 /* keys are strings. Strings will be copied with wstrdup()
 406  * and freed with wfree() */
 407
 408 extern const WMHashTableCallbacks WMStringPointerHashCallbacks;
 409 /* keys are strings, but they are not copied */
 410
 411
 412 /* ---[ WINGs/array.c ]--------------------------------------------------- */
 413
 414 /*
 415  * WMArray use an array to store the elements.
 416  * Item indexes may be only positive integer numbers.
 417  * The array cannot contain holes in it.
 418  *
 419  * Pros:
 420  * Fast [O(1)] access to elements
 421  * Fast [O(1)] push/pop
 422  *
 423  * Cons:
 424  * A little slower [O(n)] for insertion/deletion of elements that
 425  *      aren't in the end
 426  */
 427
 428 WMArray* WMCreateArray(int initialSize);
 429
 430 WMArray* WMCreateArrayWithDestructor(int initialSize, WMFreeDataProc *destructor);
 431
 432 WMArray* WMCreateArrayWithArray(WMArray *array);
 433
 434 #define WMDuplicateArray(array) WMCreateArrayWithArray(array)
 435
 436 void WMEmptyArray(WMArray *array);
 437
 438 void WMFreeArray(WMArray *array);
 439
 440 int WMGetArrayItemCount(WMArray *array);
 441
 442 /* appends other to array. other remains unchanged */
 443 void WMAppendArray(WMArray *array, WMArray *other);
 444
 445 /* add will place the element at the end of the array */
 446 void WMAddToArray(WMArray *array, void *item);
 447
 448 /* insert will increment the index of elements after it by 1 */
 449 void WMInsertInArray(WMArray *array, int index, void *item);
 450
 451 /* replace and set will return the old item WITHOUT calling the
 452  * destructor on it even if its available. Free the returned item yourself.
 453  */
 454 void* WMReplaceInArray(WMArray *array, int index, void *item);
 455
 456 #define WMSetInArray(array, index, item) WMReplaceInArray(array, index, item)
 457
 458 /* delete and remove will remove the elements and cause the elements
 459  * after them to decrement their indexes by 1. Also will call the
 460  * destructor on the deleted element if there's one available.
 461  */
 462 int WMDeleteFromArray(WMArray *array, int index);
 463
 464 #define WMRemoveFromArray(array, item) WMRemoveFromArrayMatching(array, NULL, item)
 465
 466 int WMRemoveFromArrayMatching(WMArray *array, WMMatchDataProc *match, void *cdata);
 467
 468 void* WMGetFromArray(WMArray *array, int index);
 469
 470 #define WMGetFirstInArray(array, item) WMFindInArray(array, NULL, item)
 471
 472 /* pop will return the last element from the array, also removing it
 473  * from the array. The destructor is NOT called, even if available.
 474  * Free the returned element if needed by yourself
 475  */
 476 void* WMPopFromArray(WMArray *array);
 477
 478 int WMFindInArray(WMArray *array, WMMatchDataProc *match, void *cdata);
 479
 480 int WMCountInArray(WMArray *array, void *item);
 481
 482 /* comparer must return:
 483  * < 0 if a < b
 484  * > 0 if a > b
 485  * = 0 if a = b
 486  */
 487 void WMSortArray(WMArray *array, WMCompareDataProc *comparer);
 488
 489 void WMMapArray(WMArray *array, void (*function)(void*, void*), void *data);
 490
 491 WMArray* WMGetSubarrayWithRange(WMArray* array, WMRange aRange);
 492
 493 void* WMArrayFirst(WMArray *array, WMArrayIterator *iter);
 494
 495 void* WMArrayLast(WMArray *array, WMArrayIterator *iter);
 496
 497 /* The following 2 functions assume that the array doesn't change between calls */
 498 void* WMArrayNext(WMArray *array, WMArrayIterator *iter);
 499
 500 void* WMArrayPrevious(WMArray *array, WMArrayIterator *iter);
 501
 502
 503 /* The following 2 macros assume that the array doesn't change in the for loop */
 504 #define WM_ITERATE_ARRAY(array, var, i) \
 505     for (var = WMArrayFirst(array, &(i)); (i) != WANotFound; \
 506     var = WMArrayNext(array, &(i)))
 507
 508 #define WM_ETARETI_ARRAY(array, var, i) \
 509     for (var = WMArrayLast(array, &(i)); (i) != WANotFound; \
 510     var = WMArrayPrevious(array, &(i)))
 511
 512 /* ---[ WINGs/bagtree.c ]------------------------------------------------- */
 513
 514 /*
 515  * Tree bags use a red-black tree for storage.
 516  * Item indexes may be any integer number.
 517  *
 518  * Pros:
 519  * O(lg n) insertion/deletion/search
 520  * Good for large numbers of elements with sparse indexes
 521  *
 522  * Cons:
 523  * O(lg n) insertion/deletion/search
 524  * Slow for storing small numbers of elements
 525  */
 526
 527 #define WMCreateBag(size) WMCreateTreeBag()
 528
 529 #define WMCreateBagWithDestructor(size, d) WMCreateTreeBagWithDestructor(d)
 530
 531 WMBag* WMCreateTreeBag(void);
 532
 533 WMBag* WMCreateTreeBagWithDestructor(WMFreeDataProc *destructor);
 534
 535 int WMGetBagItemCount(WMBag *bag);
 536
 537 void WMAppendBag(WMBag *bag, WMBag *other);
 538
 539 void WMPutInBag(WMBag *bag, void *item);
 540
 541 /* insert will increment the index of elements after it by 1 */
 542 void WMInsertInBag(WMBag *bag, int index, void *item);
 543
 544 /* erase will remove the element from the bag,
 545  * but will keep the index of the other elements unchanged */
 546 int WMEraseFromBag(WMBag *bag, int index);
 547
 548 /* delete and remove will remove the elements and cause the elements
 549  * after them to decrement their indexes by 1 */
 550 int WMDeleteFromBag(WMBag *bag, int index);
 551
 552 int WMRemoveFromBag(WMBag *bag, void *item);
 553
 554 void* WMGetFromBag(WMBag *bag, int index);
 555
 556 void* WMReplaceInBag(WMBag *bag, int index, void *item);
 557
 558 #define WMSetInBag(bag, index, item) WMReplaceInBag(bag, index, item)
 559
 560 /* comparer must return:
 561  * < 0 if a < b
 562  * > 0 if a > b
 563  * = 0 if a = b
 564  */
 565 void WMSortBag(WMBag *bag, WMCompareDataProc *comparer);
 566
 567 void WMEmptyBag(WMBag *bag);
 568
 569 void WMFreeBag(WMBag *bag);
 570
 571 void WMMapBag(WMBag *bag, void (*function)(void*, void*), void *data);
 572
 573 int WMGetFirstInBag(WMBag *bag, void *item);
 574
 575 int WMCountInBag(WMBag *bag, void *item);
 576
 577 int WMFindInBag(WMBag *bag, WMMatchDataProc *match, void *cdata);
 578
 579 void* WMBagFirst(WMBag *bag, WMBagIterator *ptr);
 580
 581 void* WMBagLast(WMBag *bag, WMBagIterator *ptr);
 582
 583 /* The following 4 functions assume that the bag doesn't change between calls */
 584 void* WMBagNext(WMBag *bag, WMBagIterator *ptr);
 585
 586 void* WMBagPrevious(WMBag *bag, WMBagIterator *ptr);
 587
 588 void* WMBagIteratorAtIndex(WMBag *bag, int index, WMBagIterator *ptr);
 589
 590 int WMBagIndexForIterator(WMBag *bag, WMBagIterator ptr);
 591
 592
 593 /* The following 2 macros assume that the bag doesn't change in the for loop */
 594 #define WM_ITERATE_BAG(bag, var, i) \
 595     for (var = WMBagFirst(bag, &(i)); (i) != NULL; \
 596     var = WMBagNext(bag, &(i)))
 597
 598 #define WM_ETARETI_BAG(bag, var, i) \
 599     for (var = WMBagLast(bag, &(i)); (i) != NULL; \
 600     var = WMBagPrevious(bag, &(i)))
 601
 602
 603
 604 /* ---[ WINGs/data.c ]---------------------------------------------------- */
 605
 606 /* WMData handling */
 607
 608 /* Creating/destroying data */
 609
 610 WMData* WMCreateDataWithCapacity(unsigned capacity);
 611
 612 WMData* WMCreateDataWithLength(unsigned length);
 613
 614 WMData* WMCreateDataWithBytes(const void *bytes, unsigned length);
 615
 616 /* destructor is a function called to free the data when releasing the data
 617  * object, or NULL if no freeing of data is necesary. */
 618 WMData* WMCreateDataWithBytesNoCopy(void *bytes, unsigned length,
 619                                     WMFreeDataProc *destructor);
 620
 621 WMData* WMCreateDataWithData(WMData *aData);
 622
 623 WMData* WMRetainData(WMData *aData);
 624
 625 void WMReleaseData(WMData *aData);
 626
 627 /* Adjusting capacity */
 628
 629 void WMSetDataCapacity(WMData *aData, unsigned capacity);
 630
 631 void WMSetDataLength(WMData *aData, unsigned length);
 632
 633 void WMIncreaseDataLengthBy(WMData *aData, unsigned extraLength);
 634
 635 /* Accessing data */
 636
 637 const void* WMDataBytes(WMData *aData);
 638
 639 void WMGetDataBytes(WMData *aData, void *buffer);
 640
 641 void WMGetDataBytesWithLength(WMData *aData, void *buffer, unsigned length);
 642
 643 void WMGetDataBytesWithRange(WMData *aData, void *buffer, WMRange aRange);
 644
 645 WMData* WMGetSubdataWithRange(WMData *aData, WMRange aRange);
 646
 647 /* Testing data */
 648
 649 Bool WMIsDataEqualToData(WMData *aData, WMData *anotherData);
 650
 651 unsigned WMGetDataLength(WMData *aData);
 652
 653 /* Adding data */
 654
 655 void WMAppendDataBytes(WMData *aData, const void *bytes, unsigned length);
 656
 657 void WMAppendData(WMData *aData, WMData *anotherData);
 658
 659 /* Modifying data */
 660
 661 void WMReplaceDataBytesInRange(WMData *aData, WMRange aRange, const void *bytes);
 662
 663 void WMResetDataBytesInRange(WMData *aData, WMRange aRange);
 664
 665 void WMSetData(WMData *aData, WMData *anotherData);
 666
 667
 668 void WMSetDataFormat(WMData *aData, unsigned format);
 669
 670 unsigned WMGetDataFormat(WMData *aData);
 671 /* Storing data */
 672
 673 /* ---[ WINGs/tree.c ]---------------------------------------------------- */
 674
 675 /* Generic Tree and TreeNode */
 676
 677 WMTreeNode* WMCreateTreeNode(void *data);
 678
 679 WMTreeNode* WMCreateTreeNodeWithDestructor(void *data, WMFreeDataProc *destructor);
 680
 681 WMTreeNode* WMInsertItemInTree(WMTreeNode *parent, int index, void *item);
 682
 683 #define WMAddItemToTree(parent, item)  WMInsertItemInTree(parent, -1, item)
 684
 685 WMTreeNode* WMInsertNodeInTree(WMTreeNode *parent, int index, WMTreeNode *aNode);
 686
 687 #define WMAddNodeToTree(parent, aNode)  WMInsertNodeInTree(parent, -1, aNode)
 688
 689 void WMDestroyTreeNode(WMTreeNode *aNode);
 690
 691 void WMDeleteLeafForTreeNode(WMTreeNode *aNode, int index);
 692
 693 void WMRemoveLeafForTreeNode(WMTreeNode *aNode, void *leaf);
 694
 695 void* WMReplaceDataForTreeNode(WMTreeNode *aNode, void *newData);
 696
 697 void* WMGetDataForTreeNode(WMTreeNode *aNode);
 698
 699 int WMGetTreeNodeDepth(WMTreeNode *aNode);
 700
 701 WMTreeNode* WMGetParentForTreeNode(WMTreeNode *aNode);
 702
 703 /* Sort only the leaves of the passed node */
 704 void WMSortLeavesForTreeNode(WMTreeNode *aNode, WMCompareDataProc *comparer);
 705
 706 /* Sort all tree recursively starting from the passed node */
 707 void WMSortTree(WMTreeNode *aNode, WMCompareDataProc *comparer);
 708
 709 /* Returns the first node which matches node's data with cdata by 'match' */
 710 WMTreeNode* WMFindInTree(WMTreeNode *aTree, WMMatchDataProc *match, void *cdata);
 711
 712 /* Returns the first node where node's data matches cdata by 'match' and node is
 713  * at most `limit' depths down from `aTree'. */
 714 WMTreeNode *WMFindInTreeWithDepthLimit(WMTreeNode * aTree, WMMatchDataProc * match, void *cdata, int limit);
 715
 716 /* Returns first tree node that has data == cdata */
 717 #define WMGetFirstInTree(aTree, cdata) WMFindInTree(aTree, NULL, cdata)
 718
 719 /* Walk every node of aNode with `walk' */
 720 void WMTreeWalk(WMTreeNode *aNode, WMTreeWalkProc * walk, void *data, Bool DepthFirst);
 721
 722 /* ---[ WINGs/data.c ]---------------------------------------------------- */
 723
 724
 725 WMNotification* WMCreateNotification(const char *name, void *object, void *clientData);
 726
 727 void WMReleaseNotification(WMNotification *notification);
 728
 729 WMNotification* WMRetainNotification(WMNotification *notification);
 730
 731 void* WMGetNotificationClientData(WMNotification *notification);
 732
 733 void* WMGetNotificationObject(WMNotification *notification);
 734
 735 const char* WMGetNotificationName(WMNotification *notification);
 736
 737
 738 void WMAddNotificationObserver(WMNotificationObserverAction *observerAction,
 739                                void *observer, const char *name, void *object);
 740
 741 void WMPostNotification(WMNotification *notification);
 742
 743 void WMRemoveNotificationObserver(void *observer);
 744
 745 void WMRemoveNotificationObserverWithName(void *observer, const char *name,
 746                                           void *object);
 747
 748 void WMPostNotificationName(const char *name, void *object, void *clientData);
 749
 750 WMNotificationQueue* WMGetDefaultNotificationQueue(void);
 751
 752 WMNotificationQueue* WMCreateNotificationQueue(void);
 753
 754 void WMDequeueNotificationMatching(WMNotificationQueue *queue,
 755                                    WMNotification *notification,
 756                                    unsigned mask);
 757
 758 void WMEnqueueNotification(WMNotificationQueue *queue,
 759                            WMNotification *notification,
 760                            WMPostingStyle postingStyle);
 761
 762 void WMEnqueueCoalesceNotification(WMNotificationQueue *queue,
 763                                    WMNotification *notification,
 764                                    WMPostingStyle postingStyle,
 765                                    unsigned coalesceMask);
 766
 767
 768 /* ---[ WINGs/proplist.c ]------------------------------------------------ */
 769
 770 /* Property Lists handling */
 771
 772 void WMPLSetCaseSensitive(Bool caseSensitive);
 773
 774 WMPropList* WMCreatePLString(const char *str);
 775
 776 WMPropList* WMCreatePLData(WMData *data);
 777
 778 WMPropList* WMCreatePLDataWithBytes(const unsigned char *bytes, unsigned int length);
 779
 780 WMPropList* WMCreatePLDataWithBytesNoCopy(unsigned char *bytes,
 781                                           unsigned int length,
 782                                           WMFreeDataProc *destructor);
 783
 784 WMPropList* WMCreatePLArray(WMPropList *elem, ...);
 785
 786 WMPropList* WMCreatePLDictionary(WMPropList *key, WMPropList *value, ...);
 787
 788 WMPropList* WMRetainPropList(WMPropList *plist);
 789
 790 void WMReleasePropList(WMPropList *plist);
 791
 792 /* Objects inserted in arrays and dictionaries will be retained,
 793  * so you can safely release them after insertion.
 794  * For dictionaries both the key and value are retained.
 795  * Objects removed from arrays or dictionaries are released */
 796 void WMInsertInPLArray(WMPropList *plist, int index, WMPropList *item);
 797
 798 void WMAddToPLArray(WMPropList *plist, WMPropList *item);
 799
 800 void WMDeleteFromPLArray(WMPropList *plist, int index);
 801
 802 void WMRemoveFromPLArray(WMPropList *plist, WMPropList *item);
 803
 804 void WMPutInPLDictionary(WMPropList *plist, WMPropList *key, WMPropList *value);
 805
 806 void WMRemoveFromPLDictionary(WMPropList *plist, WMPropList *key);
 807
 808 /* It will insert all key/value pairs from source into dest, overwriting
 809  * the values with the same keys from dest, keeping all values with keys
 810  * only present in dest unchanged */
 811 WMPropList* WMMergePLDictionaries(WMPropList *dest, WMPropList *source,
 812                                   Bool recursive);
 813
 814 /* It will remove all key/value pairs from dest for which there is an
 815  * identical key/value present in source. Entires only present in dest, or
 816  * which have different values in dest than in source will be preserved. */
 817 WMPropList* WMSubtractPLDictionaries(WMPropList *dest, WMPropList *source,
 818                                      Bool recursive);
 819
 820 int WMGetPropListItemCount(WMPropList *plist);
 821
 822 Bool WMIsPLString(WMPropList *plist);
 823
 824 Bool WMIsPLData(WMPropList *plist);
 825
 826 Bool WMIsPLArray(WMPropList *plist);
 827
 828 Bool WMIsPLDictionary(WMPropList *plist);
 829
 830 Bool WMIsPropListEqualTo(WMPropList *plist, WMPropList *other);
 831
 832 /* Returns a reference. Do not free it! */
 833 char* WMGetFromPLString(WMPropList *plist);
 834
 835 /* Returns a reference. Do not free it! */
 836 WMData* WMGetFromPLData(WMPropList *plist);
 837
 838 /* Returns a reference. Do not free it! */
 839 const unsigned char* WMGetPLDataBytes(WMPropList *plist);
 840
 841 int WMGetPLDataLength(WMPropList *plist);
 842
 843 /* Returns a reference. */
 844 WMPropList* WMGetFromPLArray(WMPropList *plist, int index);
 845
 846 /* Returns a reference. */
 847 WMPropList* WMGetFromPLDictionary(WMPropList *plist, WMPropList *key);
 848
 849 /* Returns a PropList array with all the dictionary keys. Release it when
 850  * you're done. Keys in array are retained from the original dictionary
 851  * not copied and need NOT to be released individually. */
 852 WMPropList* WMGetPLDictionaryKeys(WMPropList *plist);
 853
 854 /* Creates only the first level deep object. All the elements inside are
 855  * retained from the original */
 856 WMPropList* WMShallowCopyPropList(WMPropList *plist);
 857
 858 /* Makes a completely separate replica of the original proplist */
 859 WMPropList* WMDeepCopyPropList(WMPropList *plist);
 860
 861 WMPropList* WMCreatePropListFromDescription(const char *desc);
 862
 863 /* Free the returned string when you no longer need it */
 864 char* WMGetPropListDescription(WMPropList *plist, Bool indented);
 865
 866 WMPropList* WMReadPropListFromFile(const char *file);
 867
 868 WMPropList* WMReadPropListFromPipe(const char *command);
 869
 870 Bool WMWritePropListToFile(WMPropList *plist, const char *path);
 871
 872 /* ---[ WINGs/userdefaults.c ]-------------------------------------------- */
 873
 874 /* don't free the returned string */
 875 const char* wusergnusteppath(void);
 876
 877 /* Free the returned string when you no longer need it */
 878 char* wdefaultspathfordomain(const char *domain);
 879
 880 /* Free the returned string when you no longer need it */
 881 char* wglobaldefaultspathfordomain(const char *domain);
 882
 883 WMUserDefaults* WMGetStandardUserDefaults(void);
 884
 885 WMUserDefaults* WMGetDefaultsFromPath(const char *path);
 886
 887 void WMSynchronizeUserDefaults(WMUserDefaults *database);
 888
 889 void WMSaveUserDefaults(WMUserDefaults *database);
 890
 891 void WMEnableUDPeriodicSynchronization(WMUserDefaults *database, Bool enable);
 892
 893 /* Returns a WMPropList array with all the keys in the user defaults database.
 894  * Free the array with WMReleasePropList() when no longer needed.
 895  * Keys in array are just retained references to the original keys */
 896 WMPropList* WMGetUDKeys(WMUserDefaults *database);
 897
 898 WMPropList* WMGetUDObjectForKey(WMUserDefaults *database, const char *defaultName);
 899
 900 void WMSetUDObjectForKey(WMUserDefaults *database, WMPropList *object,
 901                          const char *defaultName);
 902
 903 void WMRemoveUDObjectForKey(WMUserDefaults *database, const char *defaultName);
 904
 905 /* Returns a reference. Do not free it! */
 906 char* WMGetUDStringForKey(WMUserDefaults *database, const char *defaultName);
 907
 908 int WMGetUDIntegerForKey(WMUserDefaults *database, const char *defaultName);
 909
 910 float WMGetUDFloatForKey(WMUserDefaults *database, const char *defaultName);
 911
 912 Bool WMGetUDBoolForKey(WMUserDefaults *database, const char *defaultName);
 913
 914 void WMSetUDStringForKey(WMUserDefaults *database, const char *value,
 915                          const char *defaultName);
 916
 917 void WMSetUDIntegerForKey(WMUserDefaults *database, int value,
 918                           const char *defaultName);
 919
 920 void WMSetUDFloatForKey(WMUserDefaults *database, float value,
 921                         const char *defaultName);
 922
 923 void WMSetUDBoolForKey(WMUserDefaults *database, Bool value,
 924                        const char *defaultName);
 925
 926 WMPropList* WMGetUDSearchList(WMUserDefaults *database);
 927
 928 void WMSetUDSearchList(WMUserDefaults *database, WMPropList *list);
 929
 930 extern char *WMUserDefaultsDidChangeNotification;
 931
 932
 933 /* ---[ WINGs/menuparser.c ]---------------------------------------------- */
 934
 935
 936 typedef struct w_menu_parser *WMenuParser;
 937
 938
 939 WMenuParser WMenuParserCreate(const char *file_name, void *file, const char *include_default_paths);
 940
 941 void WMenuParserRegisterSimpleMacro(WMenuParser parser, const char *name, const char *value);
 942
 943 void WMenuParserError(WMenuParser parser, const char *msg, ...)
 944         __attribute__ ((format (printf, 2, 3)));
 945
 946 const char *WMenuParserGetFilename(WMenuParser parser);
 947
 948 Bool WMenuParserGetLine(WMenuParser parser, char **title, char **command, char **parameter, char **shortcut);
 949
 950 void WMenuParserDelete(WMenuParser parser);
 951
 952
 953 /*-------------------------------------------------------------------------*/
 954
 955 /* Global variables */
 956
 957 extern int WCErrorCode;
 958
 959
 960 /*-------------------------------------------------------------------------*/
 961
 962 #ifdef __cplusplus
 963 }
 964 #endif /* __cplusplus */
 965
 966
 967 #endif