WINGs/NEWS

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