WINGs/NEWS

   1 ** API and ABI modifications since wmaker 0.96.0
   2 ----------------------------------------------------
   3
   4 ** libWINGs **
   5 <WINGsP.h>
   6 W_KeycodeToKeysym ADDED
   7 struct W_DragDestinationInfo: new members added SIZE CHANGE
   8
   9 <WINGs.h>
  10 WMGetTextFieldCursorPosition ADDED
  11 WC_Matrix REMOVED from enum.
  12 WMCreateProgressIndicator REMOVED
  13 WMSetProgressIndicatorMinValue REMOVED
  14 WMSetProgressIndicatorMaxValue REMOVED
  15 WMSetProgressIndicatorValue REMOVED
  16 WMGetProgressIndicatorMinValue REMOVED
  17 WMGetProgressIndicatorMaxValue REMOVED
  18 WMGetProgressIndicatorValue REMOVED
  19 typedef struct W_Ruler WMRuler REMOVED
  20 typedef struct WMRulerMargins REMOVED
  21 WMAppendTextBlock REMOVED
  22 WMAppendTextStream REMOVED
  23 WMCreateRuler  REMOVED
  24 WMCreateTextBlockWithObject REMOVED
  25 WMCreateTextBlockWithPixmap REMOVED
  26 WMCreateTextBlockWithText REMOVED
  27 WMCreateTextForDocumentType REMOVED
  28 WMDestroyTextBlock REMOVED
  29 WMFindInTextStream REMOVED
  30 WMFreezeText REMOVED
  31 WMGetGrabbedRulerMargin REMOVED
  32 WMGetReleasedRulerMargin REMOVED
  33 WMGetRulerMargins REMOVED
  34 WMGetRulerOffset REMOVED
  35 WMGetTextBlockProperties REMOVED
  36 WMGetTextDefaultColor REMOVED
  37 WMGetTextDefaultFont REMOVED
  38 WMGetTextEditable REMOVED
  39 WMGetTextIgnoresNewline REMOVED
  40 WMGetTextInsertType REMOVED
  41 WMGetTextObjects REMOVED
  42 WMGetTextRulerShown REMOVED
  43 WMGetTextSelectedObjects REMOVED
  44 WMGetTextSelectedStream REMOVED
  45 WMGetTextSelectionColor REMOVED
  46 WMGetTextSelectionFont REMOVED
  47 WMGetTextSelectionUnderlined REMOVED
  48 WMGetTextStream REMOVED
  49 WMGetTextUsesMonoFont REMOVED
  50 WMIsMarginEqualToMargin REMOVED
  51 WMPageText REMOVED
  52 WMPrependTextBlock REMOVED
  53 WMPrependTextStream REMOVED
  54 WMRemoveTextBlock REMOVED
  55 WMReplaceTextSelection REMOVED
  56 WMScrollText REMOVED
  57 WMSetRulerMargins REMOVED
  58 WMSetRulerMoveAction REMOVED
  59 WMSetRulerOffset REMOVED
  60 WMSetRulerReleaseAction REMOVED
  61 WMSetTextAlignment REMOVED
  62 WMSetTextBackgroundColor REMOVED
  63 WMSetTextBackgroundPixmap REMOVED
  64 WMSetTextBlockProperties REMOVED
  65 WMSetTextDefaultColor REMOVED
  66 WMSetTextDefaultFont REMOVED
  67 WMSetTextDelegate REMOVED
  68 WMSetTextEditable REMOVED
  69 WMSetTextForegroundColor REMOVED
  70 WMSetTextHasHorizontalScroller REMOVED
  71 WMSetTextHasRuler REMOVED
  72 WMSetTextHasVerticalScroller REMOVED
  73 WMSetTextIgnoresNewline REMOVED
  74 WMSetTextIndentNewLines REMOVED
  75 WMSetTextRelief REMOVED
  76 WMSetTextSelectionColor REMOVED
  77 WMSetTextSelectionFont REMOVED
  78 WMSetTextSelectionUnderlined REMOVED
  79 WMSetTextUsesMonoFont REMOVED
  80 WMShowTextRuler REMOVED
  81 WMThawText REMOVED
  82 WMRefreshText REMOVED
  83 WMCreateText REMOVED
  84 WMClearText REMOVED
  85
  86
  87
  88
  89 ** libWutil **
  90 enum WMConnectionState REMOVED
  91 enum WMConnectionTimeoutState REMOVED
  92 struct ConnectionDelegate REMOVED
  93 __wmessage ADDED
  94 wstrerror REMOVED
  95 wmessage converted from function to wrapper macro
  96 wwarning converted from function to wrapper macro
  97 wfatal converted from function to wrapper macro
  98 wsyserror converted from function to wrapper macro
  99 wsyserror REMOVED (use werror instead)
 100 werror macro ADDED (replaces wsyserror)
 101 wsyserrorwithcode removed
 102 wmkdirhier ADDED
 103 wrmdirhier ADDED
 104 wmalloc0 REMOVED
 105 wnew REMOVED
 106 wnew0 REMOVED
 107 wstrlcpy ADDED
 108 wstrlcat ADDED
 109 WMPushInArray REMOVED
 110 WMWritePropListToFile NUMBER OF FUNCTION ARGUMENTS CHANGED
 111 WMGetCurrentHost
 112 WMGetHostWithName
 113 WMGetHostWithAddress
 114 WMRetainHost
 115 WMReleaseHost
 116 WMSetHostCacheEnabled
 117 WMIsHostCacheEnabled
 118 WMFlushHostCache
 119 WMIsHostEqualToHost
 120 WMGetHostName
 121 WMGetHostNames
 122 WMGetHostAddress
 123 WMCreateConnectionAsServerAtAddress REMOVED
 124 WMCreateConnectionToAddress REMOVED
 125 WMCreateConnectionToAddressAndNotify REMOVED
 126 WMCloseConnection REMOVED
 127 WMDestroyConnection REMOVED
 128 WMConnection* WMAcceptConnection REMOVED
 129 WMGetConnectionAvailableData REMOVED
 130 WMSendConnectionData REMOVED
 131 WMEnqueueConnectionData REMOVED
 132 WMFlushConnection REMOVED
 133 WMSetConnectionDelegate REMOVED
 134 WMGetConnectionService REMOVED
 135 WMGetConnectionProtocol REMOVED
 136 WMSetConnectionNonBlocking REMOVED
 137 WMSetConnectionCloseOnExec REMOVED
 138 WMSetConnectionShutdownOnClose REMOVED
 139 WMGetConnectionClientData REMOVED
 140 WMSetConnectionClientData REMOVED
 141 WMGetConnectionFlags REMOVED
 142 WMSetConnectionFlags REMOVED
 143 WMGetConnectionSocket REMOVED
 144 WMGetConnectionState REMOVED
 145 WMGetConnectionTimeoutState REMOVED
 146 WMGetConnectionUnsentData REMOVED
 147 WMGetConnectionQueuedData REMOVED
 148 WMSetConnectionDefaultTimeout REMOVED
 149 WMSetConnectionOpenTimeout REMOVED
 150 WMSetConnectionSendTimeout REMOVED
 151
 152 WMTreeWalkProc ADDED
 153 WMTreeWalk ADDED
 154 wshellquote ADDED
 155
 156
 157
 158 ----------------------------------------------------
 159
 160 *** Fri May 15 18:44:50 CEST 2015 - Christophe
 161
 162 New Tri-state type for WMButton
 163 -------------------------------
 164
 165 A new check-box type button is available with state On/Off/Tri, the later being
 166 generally used to express "leave as-is". The states are cycled through as user
 167 click on the button. It is created with:
 168   btn = WMCreateButton(parent_widget, WBTTriState);
 169
 170 There are is this case 3 possible values for WMSetButtonSelected/WMGetButtonSelected:
 171  - 0 and 1, the legacy checked/unchecked states
 172  - the new -1, when in the 3rd state
 173
 174
 175 *** Sun Dec  7 10:52:21 CET 2014 - David
 176
 177 Support for pixmap in the background of Widget
 178 ----------------------------------------------
 179
 180 The new function WMSetWidgetBackgroundPixmap was introduced to specify a pixmap
 181 that will be displayed as the background of a widget instead of the usual plain
 182 color. The dual WMGetWidgetBackgroundPixmap is provided too.
 183
 184
 185 *** Sun Nov  2 13:04:14 CET 2014 - David
 186
 187 Get the text of a button
 188 ------------------------
 189
 190 It was assumed that there was no need to retrieve the text from a button because
 191 it is generally a static constant text, but there are some cases where this can
 192 be useful, so the new function WMGetButtonText was added to the API.
 193
 194
 195 *** Thu May  9 18:24:03 CEST 2013 - Christophe
 196
 197 Const-correctness API changes for WRaster, WUtils and WINGs
 198 -----------------------------------------------------------
 199
 200 The 3 libraries have been modified to include appropriate 'const' qualifier
 201 to the function parameters that are treated as such. This should provide
 202 some hints to the compiler for better optimisation.
 203 This change should have no impact on the binary interface, and will not
 204 impact existing source code.
 205
 206 There is one exception however:
 207    WUtil: wusergnusteppath()
 208 This function now returns 'const char *' because its result must *not* be
 209 modified, so it may generate a const related warning in old code.
 210
 211
 212 *** Fri Mar  7 00:39:28 CET 2014 - David
 213
 214 New function WMCreateScaledBlendedPixmapFromFile
 215 ------------------------------------------------
 216
 217 This function can load an image from a file and if it is bigger than the
 218 specified width/height then it will be scaled down to fit the size while
 219 keeping the aspect ratio of the original image.
 220
 221
 222 *** Mon Oct 14 19:42:42 EEST 2002 - Dan
 223
 224 Double buffering
 225 ----------------
 226
 227 To avoid flickering caused by redrawing the widgets on Expose events, a
 228 double buffering technique was implemented for most of the widgets.
 229 This flickering effect has gotten more visible with the introduction
 230 of antialiased fonts. If with normal text one can redraw the text over the
 231 old one over and over again without any degradation of the text (new pixels
 232 simply overwrite old pixels), with antialiased text the situation is
 233 different and text gets quickly corrupted. To avoid this corruption, one
 234 needs to first erase the area where the text will go, which can cause the
 235 before mentioned flickering.
 236 The double buffer is implemented to solve this issue.
 237
 238 This is a change that that will be automatically available for any WINGs
 239 applications and will require no change in the existing code.
 240 However there is an exception from this in case of WMList if you delegate
 241 the drawing of items to userspace (read below for the complete details).
 242
 243
 244 *** Mon Oct 14 22:07:42 EEST 2002 - Dan
 245
 246 WMList change
 247 -------------
 248
 249 In case of WMList there is the possibility to delegate the drawing of the
 250 list items to the application that is linked with WINGs, and this code will
 251 not be inside the WINGs library, but in userland. Since we use the double
 252 buffering technique in this case too (to allow all widgets based on WMList
 253 and the ones that draw their list items by themselves to benefit from the
 254 double buffering advantage automatically), we no longer pass the window to
 255 the user code doing item drawing, but instead pass this pixmap in which we
 256 draw before copying to the real window.
 257
 258 Since one cannot use XClearWindow() or XClearArea() on pixmaps, but only on
 259 windows, if the code drawing list items used to call these functions to clear
 260 the item area before drawing it needs to change to using XFillRectangle()
 261 instead.
 262
 263 With this change it also means that there is no longer any need to do any
 264 double buffering in the user code, since it's already done by WINGs.
 265
 266
 267 *** Mon Oct 14 19:28:35 EEST 2002 - Dan
 268
 269 API change
 270 ----------
 271
 272 WMDrawString() and WMDrawImageString() no longer take a GC as argument.
 273 Instead WMDrawString() takes a WMColor* as the color for the string to be
 274 drawn, while WMDrawImageString() takes 2 WMColor* arguments in place of the
 275 old GC: first for text color and second for background color.
 276
 277 This change is required to support extending WMFont to allow it to handle
 278 antialiased fonts through the XFree86 Xft2 extension.
 279
 280 This also has the advantage of hiding low level X11 details and use WINGs
 281 internal objects instead.
 282
 283 To fix your old code to work with the new WINGs API you need to replace the
 284 GC passed to WMDraw***String() in your code with a WMColor*.
 285 Most of the old code used to be like this:
 286
 287 WMDrawString(screen, window, WMColorGC(color), font, x, y, txt, len);
 288
 289 for the new API it should be replaced by:
 290
 291 WMDrawString(screen, window, color, font, x, y, txt, len);
 292
 293 However if you used a particular GC created by yourself to suit your special
 294 needs, you need to pass a color which is the same as the foreground color of
 295 that gc.
 296
 297 For WMDrawImageString(), from:
 298
 299 WMDrawImageString(screen, window, gc, font, x, y, txt, len);
 300
 301 becomes
 302
 303 WMDrawImageString(screen, window, textColor, backColor, font, x, y, txt, len);
 304
 305 where textColor and backColor are declared like:
 306
 307 WMColor *textColor, *backColor;
 308
 309 and have the color of the foreground respective the background of the old gc.
 310
 311
 312
 313 *** Wed Oct  9 07:10:04 EEST 2002 - Dan
 314
 315 Antialiased font support
 316 ------------------------
 317
 318 With the addition of Xft2 support in the WINGs library, now WINGs can display
 319 antialiased text with TrueType or any scalable fonts.
 320
 321 Antialiased text is enabled by default, but can be disabled by adding
 322
 323 AntialiasedText = NO; in ~/GNUstep/Defaults/WMGLOBAL
 324
 325 This will disable antialiased text for any WINGs based application. If you
 326 only want to disable them for a specific application only, like WindowMaker
 327 for example, then add the same option in the applications configuration file,
 328 in this case ~/GNUstep/Defaults/WindowMaker
 329
 330 Note that bitmapped fonts look much better than TrueType when antialiasing is
 331 disabled.
 332
 333
 334 *** Mon Sep 09 06:58:30 EEST 2002 - Dan
 335
 336 New delegate for the WMConnection class
 337 ---------------------------------------
 338
 339 ConnectionDelegate structure has a new member: canResumeSending.
 340 The purpose of this callback is to notify you that you can resume sending
 341 data over a WMConnection.
 342 It works in the following manner:
 343
 344 WMSendConnectionData() can return 3 values: -1, 0, 1
 345
 346 -1 - means that the connection has died. you should stop sending data and
 347      close the connection ASAP.
 348  1 - means that the data was successfully sent
 349  0 - means that the data (or part of it) was not sent. however, it was saved
 350      in a queue and the library will try to send it later when possible.
 351
 352 if the return value is 1, you can continue to send the next message, and so
 353 on, until the return value of such a send call will be 0.
 354 After it returns 0 you can continue sending, however, the data will not be
 355 sent over the connection because the operating system cannot accept any more
 356 data for the moment. Instead it will be queued inside the library, making your
 357 program's memory footprint increase. If the amount of data you need to
 358 send is limited and not too big, this shouldn't be a problem, because your
 359 data will be queued and sent when the operating system will notify the
 360 library that sending is possible again.
 361 If this is the case you can just ignore the output of WMSendConnectionData()
 362 and not set a callback for canResumeSending.
 363
 364 However, if the amount of data you have to send is undetermined and you
 365 also want to keep a small memory footprint for your program (so that it
 366 won't grow until it uses all your available memory ;) ), you will have to
 367 stop sending data over the connection as soon as WMSendConnectionData()
 368 returns with 0. Then you should somehow mark this situation in your program
 369 to avoid it trying to send anymore data until notified that it can resume.
 370 (You should have also set a canResumeSending callback when you initialized
 371 your WMConnection object because else you cannot be notified when to resume.)
 372
 373 Now, when you receive such a 0 from the send operation, your last sent data
 374 is put in a queue inside the library. At a later time when the operating
 375 system notifies the library that sending is possible again, the library will
 376 resume to send the data that is saved in the queue. After it will be able to
 377 send all the data in the queue, the canResumeSending callback will be
 378 called, letting you know that not only you can resume sending because the
 379 operating system is again able to send data, but also that the queue was
 380 completely flushed.
 381
 382 From the canResumeSending callback, you should again update the status of
 383 your program marking that it can send again, and then resume sending the
 384 data from where you were left.
 385
 386
 387 *** Thu Oct 04 06:00:09 EEST 2001 -Dan
 388
 389 Property lists handling code
 390 ----------------------------
 391
 392 Code to handle property lists was added to WINGs. It is more robust
 393 than the libPropList code, mostly because some conflicting concepts
 394 borrowed from UserDefaults (which libPropList use) are no longer used in
 395 the WINGs property lists code. These borrowed concepts conflicted with the
 396 retain/release mechanism of property lists and could lead in certain cases
 397 to segmentation faults when executing libPropList based code. But the worse
 398 part was that these libPropList problems were practically unsolvable without
 399 removing one of those conflicting concepts and without a complete redesign.
 400 The new WINGs property lists code is also better integrated with the other
 401 data types from WINGs and is actively maintained.
 402
 403 Practically the things that were removed from the WINGs property list
 404 implementation compared to the old libPropList implementation, are exactly
 405 the UserDefaults borrowed concepts that conflict with the retain/release
 406 mechanism:
 407 - The container of a proplist object and the associated functions are gone.
 408 - The filename associated with a proplist object and the corresponding
 409   functions are gone. Now the saving function needs the filename as a
 410   parameter.
 411 - The synchronization functions are no longer supported. They are part of
 412   the UserDefaults and are implemented there.
 413 - No functions related to domains/registering were implemented in the WINGs
 414   property lists code, because they are also not part of property lists.
 415   They are more in connection with UserDefaults and a central point of access
 416   for domains.
 417
 418 The above 2 concepts: container and filename were added to libPropList just
 419 to let it support synchronization which was borrowed from UserDefaults.
 420 Property lists as defined in the openstep specification are just complex
 421 data structures composed of strings, data, arrays, dictionaries and a mix of
 422 them and are not associated with any file in particular. UserDefaults on the
 423 other hand are property lists read from a specific file and they associate
 424 that property list with that file and allow them to be synchronized.
 425
 426 Old libPropList based code can still be used by linking against the WINGs
 427 library containing the new proplist code with minimal changes which are
 428 described in detail in the comments at the top of the WINGs/proplist-compat.h
 429 header file (the same file carries the #defines for mapping old libPropList
 430 functions to the new WINGs proplist functions).
 431 Our recommendation is to move to the new functions WINGs provide because
 432 they better integrate with other function naming conventions in WINGs.
 433 The proplist-compat.h header file is just a way to have old code up and
 434 running with minimal changes so that we can remove the old and unmaintained
 435 libPropList from systems while keeping to use old libPropList based code
 436 without rewriting it and it should not be used for other purposes.
 437
 438
 439 *** Sat Apr 21 09:12:09 EEST 2001 -Dan
 440
 441 API change
 442 ----------
 443
 444 To allow a correct display of icon images with alpha blending in panels and
 445 other places where a WINGs based application may use them the following
 446 changes took place:
 447
 448 1. The following functions were renamed:
 449    - WMSetApplicationIconImage()  --> WMSetApplicationIconPixmap()
 450    - WMGetApplicationIconImage()  --> WMGetApplicationIconPixmap()
 451    - WMSetWindowMiniwindowImage() --> WMSetWindowMiniwindowPixmap()
 452 2. The following functions were added:
 453    - WMSetApplicationIconImage(WMScreen *scr, RImage *image)
 454    - RImage* WMGetApplicationIconImage(WMScreen *scr)
 455    - WMPixmap* WMCreateApplicationIconBlendedPixmap(WMScreen *scr, RColor *col)
 456
 457 As you can see the old functions that operated on WMPixmap images (which are
 458 basically X Pixmaps that lack alpha information) were renamed to ...Pixmap()
 459 to make them more suggestive about what they do and to make room for the
 460 new functions that operate on RImages (that hold alpha information).
 461
 462 Since the corresponding WMGet... functions only retrieve the stored
 463 image/pixmap from the application, I'll outline how the WMSet...
 464 functions operate:
 465
 466 All WM...IconPixmap() functions operate on WMPixmaps
 467 All WM...IconImage() functions operate on RImages
 468
 469
 470 - WMSetApplicationIconImage() will set the RImage to be used in panels
 471     and will also convert the RImage to a WMPixmap with a threshold of 128
 472     and will use that pixmap for the appicon image. If that doesn't satisfy
 473     you, you can make a call to WMSetApplicationIconPixmap() on your own to
 474     set whatever WMPixmap you see fit for the appicon.
 475
 476 - WMSetApplicationIconPixmap() will set the WMPixmap to be used for the
 477     appicon and for the panels
 478
 479
 480 If you use only one of the above functions, the corresponding image/pixmap
 481 will be used everywhere where needed (panels and appicon), but the pixmap
 482 version will not be able to handle alpha blending correctly.
 483
 484 If you use both WMSetApplicationIconImage() and WMSetApplicationIconPixmap()
 485 then the RImage will have priority in panels, and the WMPixmap will only be
 486 used for the appicon. This allows you to better control what icon is
 487 displayed in the appicon, in case the default conversion of the RImage to a
 488 pixmap with a threshold of 128 is not good enough, or in case you want a
 489 different icon to be shown in the appicon than in panels.
 490
 491
 492 Also this new function was added:
 493
 494 - WMCreateApplicationIconBlendedPixmap() will use the RImage set with
 495     WMSetApplicationIconImage() if available and will blend it with the color
 496     you passed. This will make the image show well on a background of that
 497     color. If the RImage was not set it will return NULL. You need to call
 498     WMReleasePixmap() on it after you finish with it. Passing a NULL pointer
 499     instead of a color will make the RImage be blended with the default color
 500     of the WINGs widgets: '#aeaaae' making it suitable to be assigned to any
 501     WINGs widget.
 502
 503
 504 To make your existing code work as before all you need to do is to rename
 505 the following functions:
 506
 507    - WMSetApplicationIconImage()  --> WMSetApplicationIconPixmap()
 508    - WMGetApplicationIconImage()  --> WMGetApplicationIconPixmap()
 509    - WMSetWindowMiniwindowImage() --> WMSetWindowMiniwindowPixmap()
 510
 511 But if you want to take advantage of the new abilities to show alpha
 512 blended images you need to start using the new functions.
 513
 514