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